Tips and References#

This chapter contains additional material about the git revision control system. See Setting Up Git for the minimal steps needed for Sage development.

Configuration Tips#

Your personal git configurations are saved in the ~/.gitconfig file in your home directory. Here is an example:

[user]
    name = Your Name
    email = you@yourdomain.example.com

[core]
    editor = emacs

You can edit this file directly or you can use git to make changes for you:

[user@localhost ~] git config --global user.name "Your Name"
[user@localhost ~] git config --global user.email you@yourdomain.example.com
[user@localhost ~] git config --global core.editor vim

Aliases#

Aliases are personal shortcuts for git commands. For example, you might want to be able to shorten git checkout to git co. Or you may want to alias git diff --color-words (which gives a nicely formatted output of the diff) to git wdiff. You can do this with:

[user@localhost ~] git config --global alias.ci "commit -a"
[user@localhost ~] git config --global alias.co checkout
[user@localhost ~] git config --global alias.st "status -a"
[user@localhost ~] git config --global alias.stat "status -a"
[user@localhost ~] git config --global alias.br branch
[user@localhost ~] git config --global alias.wdiff "diff --color-words"

The above commands will create an alias section in your .gitconfig file with contents like this:

[alias]
    ci = commit -a
    co = checkout
    st = status -a
    stat = status -a
    br = branch
    wdiff = diff --color-words

Editor#

To set the editor to use for editing commit messages, you can use:

[user@localhost ~] git config --global core.editor vim

or set the \(EDITOR\) environment variable.

Merging#

To enforce summaries when doing merges (~/.gitconfig file again):

[merge]
    log = true

Or from the command line:

[user@localhost ~] git config --global merge.log true

Fancy Log Output#

Here is an alias to get a fancy log output; it should go in the alias section of your .gitconfig file:

lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)[%an]%Creset' --abbrev-commit --date=relative

Using this lg alias gives you the changelog with a colored ascii graph:

[user@localhost ~] git lg
* 6d8e1ee - (HEAD, origin/my-fancy-feature, my-fancy-feature) NF - a fancy file (45 minutes ago) [Matthew Brett]
*   d304a73 - (origin/placeholder, placeholder) Merge pull request #48 from hhuuggoo/master (2 weeks ago) [Jonathan Terhorst]
|\
| * 4aff2a8 - fixed bug 35, and added a test in test_bugfixes (2 weeks ago) [Hugo]
|/
* a7ff2e5 - Added notes on discussion/proposal made during Data Array Summit. (2 weeks ago) [Corran Webster]
* 68f6752 - Initial implementation of AxisIndexer - uses 'index_by' which needs to be changed to a call on an Axes object - this is all very sketchy right now. (2 weeks ago) [Corr
*   376adbd - Merge pull request #46 from terhorst/master (2 weeks ago) [Jonathan Terhorst]
|\
| * b605216 - updated joshu example to current api (3 weeks ago) [Jonathan Terhorst]
| * 2e991e8 - add testing for outer ufunc (3 weeks ago) [Jonathan Terhorst]
| * 7beda5a - prevent axis from throwing an exception if testing equality with non-axis object (3 weeks ago) [Jonathan Terhorst]
| * 65af65e - convert unit testing code to assertions (3 weeks ago) [Jonathan Terhorst]
| *   956fbab - Merge remote-tracking branch 'upstream/master' (3 weeks ago) [Jonathan Terhorst]
| |\
| |/

Tutorials and Summaries#

There are many, many tutorials and command summaries available online.

Beginner#

Try Git is an entry-level tutorial you can do in your browser. If you are unfamiliar with revision control, you will want to pay close attention to the “Advice” section toward the bottom.
Git magic is an extended introduction with intermediate detail.
The git parable is an easy read explaining the concepts behind git.
Git foundation expands on the git parable.
Although it also contains more advanced material about branches and detached head and the like, the visual summaries of merging and branches in Learn Git Branching are really quite helpful.

Advanced#

Github help has an excellent series of how-to guides.
The pro git book is a good in-depth book on git.
Github Training has an excellent series of tutorials as well as videos and screencasts.
The git tutorial.
Git ready is a nice series of tutorials.
Fernando Perez’ git page contains many links and tips.
A good but technical page on git concepts
Git svn crash course: git for those of us used to subversion

Summaries/Cheat Sheets#

A git cheat sheet is a page giving summaries of common commands.
The git user manual.

Git Best Practices#

There are many ways of working with git; here are some posts on the rules of thumb that other projects have come up with:

Linus Torvalds on git management
Linus Torvalds on linux git workflow. Summary: use the git tools to make the history of your edits as clean as possible; merge from upstream edits as little as possible in branches where you are doing active development.

Manual Pages Online#

You can get these on your own machine with (e.g) git help push or (same thing) git push --help, but, for convenience, here are the online manual pages for some common commands: