Pre-requisites¶
To follow along, please do the following before we start:
Questions to be Answered¶
Conceptual¶
- What is Git?
- What is GitHub?
- What is version control?
- What's a repository?
- What's a commit?
- What's a fork?
- What's a branch?
- What's a diff?
- What's a conflict?
- What's a pull request?
Practical¶
- How do I push changes for others to see?
- How do I merge the changes others have made?
- How do I notify others that I have made changes?
- How can I get an overview of the repository?
- What's the difference between branches and forks and which one should I use?
What is GitHub?¶
GitHub is a Git repository hosting platform.
- Provides a central place to store your source code.
- Enables collaboration with others through pull requests.
- Also, it renders notebooks!
Getting Started to Follow Along¶
- Start your Jupyter or JupyterLab:
jupyter lab
- Open a terminal to run commands.
Demo - Commit & Push¶
- Create a new repo. – https://github.com/new
- Clone the repo locally.
git clone <repo> github-jupyter-covid
- Create a new notebook file.
- Make a plot using data from here.
- Stage, commit, and push the file back to GitHub.
git add . git commit -am "<commit message>" git push - Take a look at the Notebook on GitHub.
What's a repo (repository)?¶
- The place where all the files in your project are stored,
- Along with every version of those files that were committed,
- Including files in other branches.
What's a branch?¶
- A separate line of commits off the main branch.
- When done, we merge the branch:
- Either, back to the main branch.
- Or, into the child branch.
How does it work?¶
- GitHub hosts your team's repository.
- Your fork of the team's repo on GitHub is a full copy of the team's repo along with the full history of every file.
- Your locally cloned repo of your fork is also a full copy of the ones on GitHub.
Revisiting our Example¶
Demo - Fork & Pull Request¶
- Fork the github-jupyter/covid
- This is Shad's forked repo.
- Clone the repo locally
git clone <repo> shadanan-covid
- Update the covid notebook -- add a chart dividing confirmed cases by population.
- Use GitHub to create a pull request against upstream.
- Observe the state of your repo with:
git log --graph --all
Synchronizing Changes¶
git fetch¶
git pull (on master)¶
git push (on branch)¶
Dealing with Conflicts¶
- Jupyter notebooks aren't easy to merge because they are JSON docs.
- The best way to deal with conflicts is to avoid them.
- Don't work on the same notebook at the same time as someone else.
- Have everyone on your team make changes in a notebook with their initials.
- Have a single person be in charge of merging the final changes into the source of truth notebook.
But sometimes, you end up in a situation where you have no other choice.¶
Let's see what options we have...
Revisiting our Example¶
Demo Cont'd - nbdime (NoteBook DIff & MErge)¶
- Add
github-jupyter/covidto our remotes.git remote add upstream git@github.com:github-jupyter/covid.git
- Use
git fetch upstreamto get Niwako's changes. - Use
git log --graph --allto view the state of all the repos. - Try merging upstream/master
git merge upstream/master
- Observe that the notebook is now broken.
- Abort the merge.
git merge --abort
- Install nbdime.
pip3 install --upgrade nbdime nbdime extensions --enable
- Enable nbdime for the current repo
nbdime config-git --enable
- Run the merge again.
git merge origin/master
- Use nbdime's merge tool:
git mergetool --tool nbdime -- *.ipynb
Git Cheat Sheet¶
- Git Config
- Global:
~/.gitconfig - Repo:
.git/config
- Global:
- Status
git status
- Log / Dag
git log --graph --oneline --all
- Committing:
git add [file] git commit
- GitHub's Cheet Sheet
Summary¶
Configure git dag¶
Run:
git log --graph --all
Or, for something really special, put the following in to your ~/.gitconfig file:
[alias]
dag = log --graph --abbrev-commit --decorate --date=relative --format=format:'%C(bold blue)%h%C(reset) -%C(auto)%d%C(reset) %C(bold white)%s%C(reset)%n %C(dim white)%an%C(reset) <%ae> -%C(reset) %C(cyan)%aD%C(reset) %C(green)(%ar)%C(reset)' --allNow you can run:
git dag
Pre-requisitesTo follow along, please do the following before we start:
Install JupyterLab
Install git for your platform
Create a GitHub account