Tips and References

This chapter contains additional material about the git revision control system. It is not necessary if you stick with the Sage development scripts. 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

Summaries/Cheat Sheets

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: