Git Intro
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 git@github.com: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 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
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.
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:
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:
Once you want to commit your changes do:
When you want to share the code with others or want to merge the code back in, use:
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
Move to the feature branch you want to update with
and then merge in the changes from develop with
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
>>>>>>> developwhich you will need to edit to look like:
your and develop's changes combinedYou can then git add and resolved files and once they're all done, run
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.
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:
which allows you to write:
You can make any aliases you want and even make them run other back commands by pre-pending ! to the target.
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:
and then you can just run git lg and get a very nice pretty output with a graphical view of the branches.
Better than git pull for many cases is https://github.com/msiemens/PyGitUp
and make sure ~/.local/bin is in your path.
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.
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 indentThis will ensure that the command-line and web tools display the commit messages correctly.
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