Git workflow

Configuration

The following explains how to synchronize a local copy of nirstorm with git. It can be done using the command line or using gitkraken (free for non-commercial use) which is the recommended GUI for git. You can read the getting-started-guide, which gives a very concise presentation of how git works. To use gitkraken, download, install it and create an account as requested.

Create a fork on github (once)

To create a fork of nirstorm in your Github space, go to the main project page and click on the "Fork" button on the top right. Refer to this help page to know more about the fork process.

Your fork repository of nirstorm will be where you upload the modifications you have made locally. Then you issue a pull request to the main nirstorm repository which has to be reviewed before being incorporated (see section "Normal workflow").

The main repository and your fork version are called "remotes".

Initialize local repository (once)

The following will get the current version of nirstorm from the main github repository and store in a folder called nirstorm_trunk in the current directory:

git clone https://github.com/Nirstorm/nirstorm.git nirstorm_trunk

Under gitkraken, click on File > Clone repo. Specify the target location on your hard drive (field "Where to clone to") and fill the URL field with: https://github.com/Nirstorm/nirstorm.git.

Remotes

Configure remote repos:

git remote -v # show all remote repo

The origin repository (main nirstorm github repository) should already bet set to https://github.com/Nirstorm/nirstorm.git.

Add your fork repository as the upstream remote (replace user_name with your user name).

Using ssh::

git remote add upstream [email protected]:user_name/nirstorm.git #my fork of repo (forked on github), uses ssh

Using https::

git remote add upstream https://github.com/user_name/nirstorm.git [email protected]:user_name/nirstorm.git

Under gitkraken, use the plus sign (+) located in the left panel under the section "REMOTE".

To locally checkout pull requests (PRs)

in the file nirstorm/.git/config : to the section origin, add the line fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

Normal Workflow

Prepare new feature -> describe the feature on GitHub with a ticket or assign yourself to an existing one	open a new issue on GitHub and label it or work on existing ticket
Start a new feature -> create a new descriptively-named branch	git checkout -b new-dev
Write doc, tests, implement -> Declare files to be commited	git add new_dev.rst test_new_dev.py new_dev.py
When a sub-stuff seems completed -> commit locally	git commit -m '[#<ticket_number>] my stuff started'
Loop while working	git add ... ; git commit -m '[#<ticket_number>] ...'
Before pushing upstream, check that you are up to date with master branch in main repository.	git fetch origin; git checkout master; git merge origin/master
If previous command updated your master branch rebase your feature branch on master. Resolve conflicts if any.	git checkout new-dev; git rebase master
When the feature is ready to publish -> push to your fork of nirstorm on your github	git push upstream new-dev
To ask for feedback and for merge on master -> do a pull-request on Github -> indicate that the PR is closed	Login to your github account an open a Pull-request from it
Someone else review your PR they have to checkout the PR	git cmds: git fetch origin git checkout pr/<PR_ID>
If someone else wants to checkout updated PR	git cmds: git fetch origin git checkout pr/<PR_ID> git merge origin/pr/<PR_ID>
See comments on the PR on github Wait for close or approval
Once PR is treated, if merge occured switch to master branch update master from official repo	git cmds: git checkout master git pull origin
Close the dev of the new feature locally on github	git cmds: git branch -d new-dev git push upstream --delete new-dev

Sketch of the workflow:

## official repo on Github ##                          ## fork on user account ##
 nirstorm:nirstorm/master        /_____PR______        __  user:nirstorm/my-branch
                                 \                      /\
            \                                          /
             \                                        /
              \                                      /
      git pull origin                 git push upstream my-branch
                \                                 /
                _\|      ## local repo  ##       /
             origin/master            upstream/my-branch

Misc useful commands

• Show a nice history log:

  git log --oneline --decorate --color --graph
  git log --pretty=format:"%C(auto)%h %ar %d %s %C(bold blue)<%an>%Creset" --decorate --color --graph
  

• You can also add an alias:

  git config --global alias.hist 'log --pretty=format:"%C(auto)%h %ar %d %s %C(bold blue)<%an>%Creset" --decorate --color --graph'
  
  git hist