Git Intro

Introduction to Git

I'm not going to try to write a full Git tutorial since that's been done so well by so many other. If you're brand-new to Git and have never used it before I recommend going to https://try.github.io and doing that tutorial. Atlassian also have a good set of tutorials about how to use Git for most usual tasks at https://www.atlassian.com/git/tutorials/.

The URL of our repository will be [email protected]:ganga-devs/ganga.git or https://github.com/ganga-devs/ganga.git depending on which method you want to use. They both do the same thing but can use different authentication methods.

We will be hosting Ganga on GitHub so you will need a GitHub account to upload code. You can join at https://github.com/join and once you have, tell one of the other developers your GitHub username so you can be added to the team.

Git workflow

Git itself does not prescribe a workflow but we have decided to use a specific one. It is called git-flow and is described at http://nvie.com/posts/a-successful-git-branching-model/. The summary of it is that all development work happens on the develop branch. When a release is made, a branch is taken from develop, tested until we are happy and then merged into master. This way, master will only contain released code.

While all development work occurs on develop, it is encouraged to not commit directly to that branch. Git makes creating and managing branches very easy and so what should be done is to make a branch from develop, make your changes there and then merge them back when that feature is finished. git-flow says these branches should be named feature/<name-here>. If it is a small feature you do not have to upload (or 'push') you branch while it is being worked on but if it is a large feature which you want other to collaborate on then pushing the branch is a good idea.

To make life easier, there is a git plugin you can download which provides built-in functionality for following the git-flow model. The code is available at https://github.com/nvie/gitflow and the documentation is at https://github.com/nvie/gitflow/wiki/Command-Line-Arguments

Cloning the repo

To make a local copy of the code you need to first clone the repo and then run the git-flow initialisation to set up the branches correctly.

git clone [email protected]:ganga-devs/ganga.git #Get the code
git branch master origin/master #Track the master branch too
git flow init -d #Set up git-flow with the defaults

Making a new feature

To demonstrate this, to start from a case where you have checked out the code locally using the instructions above to where the feature is scheduled for the next release you need to do the following:

git flow feature start my-feature

This has created a branch called feature/my-feature which will contain your code while working on it. At this point you can start making changes to the code and running unit tests to make sure it works. To keep track of what you have changed you can do:

git status
git diff

Once you want to commit your changes do:

git add python/Ganga/Core/exceptions.py #Or whatever
git commit #This will open a text editor for the commit message

When you want to share the code with others or want to merge the code back in, use:

git flow feature publish my-feature

which will push the branch to GitHub where everyone can see it. To merge the code back into develop we use GitHub's pull request functionality. Find your branch on the list of branches and press the 'New pull request' button on the right. Type a nice descriptive message about what the feature does and how it works and press 'Create pull request'.

Once other people have commented on your code and it's agreed that it should be merged, press the 'Merge pull request' button at the bottom (you might need to update your branch from develop for this to work).

Any code in develop will be included in the next release.

To clean up, delete your local branch with

git checkout develop
git pull
git branch -d feature/my-feature

Updating a long-lived branch to develop

Move to the feature branch you want to update with

git flow feature checkout my-new-feature

and then merge in the changes from develop with

git merge develop

It will automatically merge everything it can but if there are any conflicts then it will inform you. Open those files and manually fix the merge. The merge conflict in the file will look something like:

<<<<<<< HEAD
your changes
=======
develop's changes
>>>>>>> develop

which you will need to edit to look like:

your and develop's changes combined

You can then git add and resolved files and once they're all done, run

git commit

There's some more help in the GitHub Help Centre.

Useful tools and aliases

Apart from git-flow which has already been mentioned, there are a number of useful tools for working with Git.

Aliases

Like an alias in bash, it's possible to make shortcuts to make daily life a little easier. At the very least I recommend adding shortcuts for commit, status and checkout. You do this using the git config command. Run:

git config --global alias.ci commit
git config --global alias.st status
git config --global alias.co checkout

which allows you to write:

git co develop #Checks out the develop branch

You can make any aliases you want and even make them run other back commands by pre-pending ! to the target.

Pretty log

git log will print a list of all the commits on the current branch in a similar way to svn log. You can make it give you more information though using the method described at A better git log. All you need to do is add an alias for git lg with:

git config --global alias.lg "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

and then you can just run git lg and get a very nice pretty output with a graphical view of the branches.

git up

Better than git pull for many cases is https://github.com/msiemens/PyGitUp

pip install git-up --user

and make sure ~/.local/bin is in your path.

Other tools

tig is an interactive version of git log with some very nice features.

gitk is a GUI version of the same.

git gui is a built-in tool for making commits and pushing. It's useful for being able to easily commit only certain lines from files.

Style stuff

When committing is a good idea if everyone follows a similar Git commit format. The recommendation from Tim Pope and discussed by Chris Beams is to follow a template like:

Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug."  This convention matches up with commit messages generated
by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space, with blank lines in between, but conventions vary here

- Use a hanging indent

This will ensure that the command-line and web tools display the commit messages correctly.

Understanding Git

If you want to understand a but about why Git works how it does or how things are structured, there is a good post at http://tom.preston-werner.com/2009/05/19/the-git-parable.html