### Navigation

- index
- modules |
- next |
- previous |
- Developer's Guide v6.4.1 »

# 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 implimentation 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

- 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.
- A git cheat sheet is a page giving summaries of common commands.
- The git user manual.
- The git tutorial.
- Git ready is a nice series of tutorials.
- 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.
- 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

## 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:

- git add
- git branch
- git checkout
- git clone
- git commit
- git config
- git diff
- git log
- git pull
- git push
- git remote
- git status

### Navigation

- index
- modules |
- next |
- previous |
- Developer's Guide v6.4.1 »