IRB Git Instructions

Instructions for VHbb AnalysisTools

These instructions cover a typical workflow one would encounter when doing developments in the AnalysisTools package and wanting to make a GitHub pull request. Your staring point is likely the one where you already have your local repository set up after following the AnalysisTools instructions to download and compile the code. In case you are starting from scratch, the very first step is to clone the main AnalysisTools repository

git clone https://github.com/capalmer85/AnalysisTools.git

NOTE: In case you don't care about the full development history, you could get by with only the latest snapshot of the repository by doing

git clone --depth=1 https://github.com/capalmer85/AnalysisTools.git

Before making and committing any code changes, make sure you first create a new development branch (the branch name is arbitrary, here myDev is used as an example)

git checkout -b myDev

Doing developments on a dedicated branch different from the master branch is good practice which saves you from potential headaches further down the road. You are now ready to start developing using the usual Git commands

git add ...
git commit -m "..."
...

Once you are done with the code development, you need to push your development branch to your fork of the main AnalysisTools repository. Here it is assumed that you have already set it up (for general instructions on how to make a fork, have a look here). Add your fork as a remote repository to your local repository as follows

git remote add myFork https://github.com/<username>/AnalysisTools.git

Now push the branch to your fork

git push myFork myDev

You are now ready to make a pull request. Open your forked repository link in a browser and click on the 'New pull request' button, select your development branch as the branch which will be used to make the pull request and click on the 'Create pull request' button. Give your pull request a title which is not too long but captures its content as much as possible, describe the pull request in more detail in the description box and finally click on the 'Create pull request' button one more time. Now you should follow your pull request and respond to any comments you might receive from the repository admins or implement any changes in case they are requested.


It often happens that while your pull request is under review, some other pull request gets merged and causes a merge conflict for your pull request. In case that happens, you will first need to resolve the conflict before your pull request can be merged. For this it is best to rebase your development branch and the procedure to do this is the following. First, switch to the local master branch and synchronize it with the main repository

git checkout master
git pull --ff-only origin master

NOTE: The --ff-only option means that a fast-forward merge of the remote master branch must be done. If not possible, the pull will fail. This is an extra sanity check because under normal circumstance even a plain git pull would perform a fast-forward merge. In case it fails, this is a sign of something not being quite as expected (perhaps you made some commits on the local master branch, etc.) and you need to understand why git pull failed before you can proceed.

Next, switch back to the development branch

git checkout myDev

If you want to be extra cautious, it is probably not a bad idea to create a backup of the development branch before rebasing

git branch myDev_backup

It can also be useful to look at the topology of your local branches before rebasing

git log --graph master myDev myDev_backup

Make one final check that you are sitting on the development branch

git branch

and if so, you are now ready to rebase

git rebase master

This will replay all your commits from the myDev branch on top of the local master branch. At one point you will be prompted about a merge conflict which you will need to resolve manually by opening and editing the affected file(s) in your favorite text editor. The sections of the code affected by the merge conflict will be enclosed by

<<<<<<<
...
>>>>>>>

Once you are done with editing, mark the conflict as resolved using git add

git add <path/to/file>

Just to make sure that all changes look as expected, run

git diff

If everything looks ok, you can continue with rebasing

git rebase --continue

In case additional merge conflicts appear, repeat the above procedure. Once you are done with rebasing, it can be useful to check the topology of your local branches after rebasing

git log --graph master myDev myDev_backup

Finally, you need to update your pull request by force-pushing (note the -f option) the rebased development branch to GitHub

git push -f myFork myDev


Once your pull request has been merged, you can return to your local master branch and synchronize it with the main repository

git checkout master
git pull --ff-only origin master

Using tags

A very useful feature in Git is tagging. What it does is essentially giving a user-defined name to a specific version of the code. For example, if you would like to share your development branch with someone else, one possibility would be to ask the other person to do the following

git clone -b myDev https://github.com/<username>/AnalysisTools.git

where <username> is your GitHub user name. With this command, while cloning your fork of the AnalysisTools, the other person will automatically checkout your development branch and will be ready to test the code. However, Git branches are by construction not static and in case you continue developing on that same branch, depending on when the other person executes the above command, she/he might end up with a version of your code that was not really intended for testing. It is, therefore, much better to use tags to share a frozen version of the code. For this you first need to tag the code (here it is assumed you are currently sitting on your development branch and the tag name is v1.0_beta)

git tag v1.0_beta

and then push the tag to your fork

git push myFork v1.0_beta

The updated clone command the other person would now execute is

git clone -b v1.0_beta --depth=1 https://github.com/<username>/AnalysisTools.git

The --depth=1 option can be left out but it ensures that only the specified tagged version of the code is cloned without downloading the full history of the repository prior to this tagged version. Because of their static nature, tags are generally used for official releases of various software packages.

General comments and suggestions

  • NEVER do any developments directly on the local master branch, ALWAYS use a dedicated development branch
  • Make your commits atomic instead of monolithic
  • If your pull request has merge conflicts, NEVER merge master branch into your development branch to resolve merge conflicts. Use git rebase instead
  • Once your pull request has been merged, delete your development branch from your forked repository
  • In general, use force-pushing with great care as it is destructive for the remote branch (it rewrites history)
  • In general, it is a good practice to keep your commit history clean. It is therefore recommended to squash commits fixing typos or doing other trivial changes with other commits using either the interactive rebasing (git rebase -i HEAD~N, where N is the number of the most recent commits you want to replay, and using the fixup command for commits to be squashed) or the --amend option of git commit command if trivial fixes can be incorporated within the last commit
  • NEVER use branches as part of any shared software recipes. It is a quite common but very bad habit. Use tags instead

Additional resources

-- DinkoFerencek - 2020-05-07

Edit | Attach | Watch | Print version | History: r5 < r4 < r3 < r2 < r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r5 - 2020-09-24 - DinkoFerencek
 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    Main All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback