I've fiddled with my blog template because I decided I wanted more horizontal viewing space, given that it was using less than a third of my 1920 horizontal pixels. If it feels too spread out for you, I added a drag-and-drop handle over to the left to let you resize the main content column. The javascript is pretty primitive. If it breaks, drop me a comment.
>
>
>
>

Friday, January 22, 2010

Git Quick Reference

I've been lazy/sick/on vacation for a while, but I think I'm finally ready to release my Git Quick Reference into the wild. It's kind of a follow-up to my series of Git tutorial posts, collecting all the important stuff into one, relatively short document for easy access once you've started down the road of learning your way around Git. It's available on Scribd: Git Quick Reference Google Docs: Git Quick Reference

Update (2013-04-19): Since Scribd apparently no longer offers free access, here's the Quick Reference available via my Google Drive. I'm also attempting to include it inline here for convenience. I've made little effort to ensure it looks right here. It's just a quick export from LibreOffice plus a little minor surgery to clean up the major flaws. I recommend the PDF for serious use.

TOC

Articles in this series:



Note: The handful of useful diagrams don't appear in the inline version below. At the moment, see the PDF for the complete version!



- no title specified

Git Quick Reference

This is a quick reference for Git, the DVCS. If you're looking for more detailed help than what's here, see the “Additional references” listed at the end of this document. My email address is there as well, and if you have questions I may be able to help answer them.

I've tried to list the most commonly used/useful commands here. They're broken up into a handful of categories describing general activities you perform in Git. Most commands have multiple variants, listed separately, composed of different options and arguments. A few commands have variants listed under multiple categories because they have quite varied uses. Options that apply to multiple variants of a command are listed to the far right.

Setting up the repo

Use these commands to create and configure a repository and get up and running with Git.

git init

Create a repo in the current directory.

--bare

Create a bare repo (no working tree)

git clone <url>

Clone the repo at the given URL into a local directory.

git clone <url> <dir>

Clone into the specified directory.

git config <key> <value>

Set the "key" to "value" in the config file.

--global

Change user-wide configuration.

--system

Change system-wide configuration.

git config -–unset <key>

Remove "key" from the config file.

git config -e|--edit

Edit the config file.

Getting things into your repo

 
These commands deal with turning your work into history (commits) stored in the repository. There are four areas that can hold changes, where a "change" is roughly equivalent to a new file, a removed file, or a modification to an existing file.
 
  1. 1) Working tree—This is your workspace. As soon as you change a file, you've changed your working tree. 

  2. 2) Index—This is a staging area for changes that are ready to be committed to the repository. When a change is staged to the index, it is no longer considered to be in your working tree, though your filesystem still reflects changes that have been staged. You stage changes when preparing to commit them. 

  3. 3) Repository—Upon commit, any and all staged changes turn into a commit in the repository. Commits are a permanent part of history. 

  4. 4) Stash—This is an out-of-sight holding area for changes. When you stash changes, they are no longer in your working tree, and the filesystem doesn't reflect them anymore, either. 

The diagram to the right roughly illustrates the flow of changes around your local repository.

The commit is the basic building block of a Git repository. Each commit has, among other things, an author, a timestamp, 0 or more parent commits, and a complete snapshot of the state of the project when the commit was made. Every commit is identified by a SHA-1 hash that is calculated from the previously mentioned properties plus some. This means that if two commits have the same hash, then they have the same parent(s), author, etc. This identity is unique even across repositories.

git add <path> [<path>...]

Stage files and directories to the index. Directories are staged recursively.

git add -p [<path>...]

Interactively choose what to stage for commit.

git mv <src> <dest>

Stage a file rename.

git add --all

Stage everything, including deletions and untracked files.

git rm <file>

Stage a file deletion.

git rm -r <dir>

Stage a recursive directory deletion.

git commit

Commit staged changes to your local repository. Opens your configured editor for a commit message.

-m "message"

Specify commit message on command line.

-C <commit>

Use the message from the given commit for this commit. Very useful in conjunction with --amend to reuse the last commit message (-C HEAD).

git commit <path> [<path>...]

Commit changes in the given files and/or directories.

git commit -a

Stage and commit all changes to tracked files.

git commit --amend

Alter the most recent commit to also contain staged changes.

Housekeeping

This group of commands is for moving changes between the working tree, index, and stash. At first, the stash may feel like an odd thing to have in a VCS, but it will soon become second nature. A typical workflow goes like this:

  • code, code, code 

  • boss brings a hot bug that needs fixing NOW 

  • git stash 

  • fix bug 

  • commit 

  • git stash pop 

  • code, code, code 

Any time you need a quick place to shove aside your in-progress work, the stash is there waiting.

git reset

Unstage all changes. I.e. move them from the index back to the working tree.

git reset <path> [<path>...]

Unstage changes to the given files and directories.

git clean -f

Delete any non-ignored, untracked files in your working tree.

-n

Dry run; only show what would be deleted.

git clean -fd

Delete directories as well as files.

git checkout <path> [<path>...]

Revert working tree changes to the given files and directories. Doesn't affect staged changes.

git stash

Push all changes in the working tree and index onto the top of the stash. (Acts like a stack.)

git stash list

List each stash that's been made..

git stash apply

Apply most recent stash to the working tree.

stash@{n}

Use stash number n instead of most recent stash.

git stash pop

Apply most recent stash and remove it (if no conflicts occur).

git stash drop

Delete most recent stash.

git stash show

Show a diffstat of the most recent stash.

git stash show -p

Show a diff of the most recent stash.

Working with branches

Branches in Git are lightweight and highly flexible. In fact, a branch is little more than a Post-it note stuck to a commit that shows where the tip of the branch is. When a new commit is made at the branch tip, the Post-it moves to the new commit. Since a branch is so light, it has no knowledge of the commits it contains within itself. It just points at a commit and is considered to "contain" all ancestors of that commit. The ancestry determines the content of the branch, and it makes merging relatively trivial. To merge n branches, a new commit is created which has n parents. Each parent was the tip of one of the branches being merged. The new commit then shares the ancestry of all n branches. As you come to understand the concept of ancestry determining branch content, you'll begin to understand the power that Git places at your fingertips.

While Git is very good at merging, conflicts are sometimes unavoidable. When a conflict occurs, the merge won't be committed automatically. Instead, successfully merged files will be left in your index, and unmerged files will be in your working tree. To finish the merge, resolve the conflicts, stage the unmerged files, and do the commit yourself. Note that merge conflicts occur not only when merging, but can also happen when popping a stash, rebasing, performing remote operations, or anything else that involves combining commits somehow. For information on integrating Git with various merge tools, check out the "merge.tool" option of git config.

git branch

List local branches.

git branch -r

List remote-tracking branches.

git branch -a

List all branches (remote and local).

git branch <name>

Create a branch with the given name at your current commit.

--track

Use with the second form above to create a branch that tracks another branch, typically a remote branch. Then remote operations on the new branch will automatically use the tracked remote branch.

git branch <name> <commit>

Create a branch with the given name pointing at the given branch or commit.

git checkout <branch name>

Make the given branch your current branch. Your working tree will reflect the state of the commit at the tip of the branch, and new commits will be applied to the branch.

git checkout <commit>

Make your working tree reflect the given commit. You won't be on a branch, and any commits made will be lost if you don't create a branch to contain them.

git checkout -b <name>

Create a new branch with your currently checked-out commit as its parent, and check out the new branch.

git checkout -b <name> <commit>

Like the git branch command of similar form, but checks out the new branch.

git branch -d/-D <name>

Delete the given branch. If not an ancestor of your current branch, you must force deletion with -D.

git merge <branch name>

Merge the given branch into your current branch.

git merge <branch name> -m "message"

Perform a merge using the given message for the commit created by the merge.

git cherry-pick <commit>

Copy the given commit to your current branch.

git reset <commit>

Move to the given commit, making it your HEAD and the tip of your current branch. Changes introduced are left in working tree.

git reset --soft <commit>

Same as above, but leave changes in the index.

git reset --hard <commit>

Same as above, but don't leave changes anywhere.

Rebasing

While this really belongs to the section on branches, it's a difficult concept, so I gave it its own spot. If you're coming from a centralized VCS, rebasing will take some time to wrap your head around. To make it as simple as possible, think of the commits in a branch like they're links in a chain. A rebase lets you measure out a length of the chain, cut it off at a particular link, then reattach the part you cut off to a different link somewhere else, maybe even on a different chain.

On top of that, a rebase actually reattaches a single link of the chain at a time, and you can tell it to let you modify and reorder the links (commits) as it applies them. This is called an "interactive" rebase. You can even use it to go back in history and make some changes without even moving anything.

If a rebase is interrupted by a conflict or if you're doing an interactive rebase and choose to modify a commit during the process, you'll have to give Git further instructions after you do your work. When a rebase stops, it will stop after a commit's changes have been applied to the index and/or working tree, but before the changes are committed. At that point, you can continue it, abort it, or skip the commit that it stopped on.

git rebase <commit>

Take commits in the current branch that aren't ancestors of the given commit, and move them onto the given commit. (<commit> = green; moved commits = purple)

git rebase --onto <commit2> <commit1>

Like above, but move to the "onto" commit instead. This lets you specify a range of commits to be "clipped" and moved over to any arbitrary commit. (<commit1> = orange; <commit2> = green; moved commits = purple)

git rebase -i <commit>

Rewind all commits back to <commit>, and reapply them, optionally editing commits along the way. In fact, any rebase operation can be made interactive by supplying this flag.

git rebase --continue

Continue an interrupted rebase.

git rebase --abort

Abort an interrupted rebase, returning to the state before the rebase started.

git rebase --skip

Skip the current commit and continue with the rebase. The skipped commit won't appear in the final result.

Working with other repos

This section has all the commands you need to communicate between repositories. Remoting is a key part of Git. It's what makes Git distributed. Remoting in Git consists of connecting a repository to other ones (remotes) and of pushing and pulling commits to and from those repositories. You provide a name and a URL when you configure a remote. The name is your identifier for a remote, and the URL is how Git locates it. There are a number of supported transports, but all use a similar URL format:

  •  rsync://host.xz/path/to/repo.git/ 

  •  http://host.xz/path/to/repo.git/ 

  •  https://host.xz/path/to/repo.git/ 

  •  git://host.xz/path/to/repo.git/ 

  •  ssh://[user@]host.xz[:port]/path/to/repo.git/ 

  •  file:///path/to/repo.git/ 

For a fuller treatment of URLs, see "GIT URLS" in "git help pull".

When you use remote repositories, Git automatically creates branches called "remote-tracking" branches that store the state of those remotes. You never work directly on a remote-tracking branch. They're just mirrors of your remotes that are used as synchronization points for pushing and pulling commits.

It's worth mentioning that when you clone a repository, Git creates a remote in the new repository named "origin" that points at the repository you cloned.

git remote

List this repository's remotes.

git remote add <name> <url>

Add a remote repository with the given name and located at the given URL.

git remote rename <old> <new>

Change the name of a remote repository. Updates branch names and the remote configuration as well.

git remote rm <name>

Remove a remote repository and its remote-tracking branches and configuration entries.

git fetch

Fetch unfetched commits from all branches in the remote named "origin" into remote-tracking branches.

git fetch <remote name>

Fetch from the given remote instead of "origin".

git pull <remote name> <branch>

Fetch a branch from a remote and merge it into your current working branch.

git push

Push all new commits in "matching" branches to the remote named "origin". A "matching" branch is one that exists both locally and on the remote.

--all

Push all local branches, creating them in the remote if they don't exist.

git push <remote name>

Push matching branches to the given remote.

git push <remote name> <branch>

Push the given branch to the given remote.

Seeing the things in your repo

These commands are all read-only and give you different ways of looking at the history of your files. Many Git commands take a commit as input. In this guide, that is generally denoted with the placeholder <commit>. Most of these commands actually accept what's known as a "treeish", meaning anything that can be dereferenced to a "tree", which is an internal object stored by Git. Here are some popular forms that a treeish comes in:

  • commit hash: c42b40edc2b5b09e565e20663079e9c14b37aa21 

  • small, unique part of a commit hash: c42b4 

  • branch name: master 

  • special "current commit" ref: HEAD 

  • the suffix "^" indicates "parent of": HEAD^ master^ c42b4^ 

  • "^" applies multiple times: HEAD^^^ 

See "SPECIFYING REVISIONS" in "git help rev-parse" for more ways of naming a commit/treeish.

git status

Display paths with uncommitted changes. Shows three sections: changes in the index, changes in the working tree, and files not being tracked by Git.

git log

Show the history of your current branch or commit.

-p

Under each commit shown in the log, show a diff of the changes introduced by that commit.

--stat

For each commit, show a summary of files changed by the commit.

git log <commit>

Show history a particular branch or commit instead of the current one.

git log <path> [<path>...]

Only show commits that affect the give path(s).

git diff

Show changes in the working tree relative to the index.

--staged|--cached

Show changes that are in the index instead of the working tree.

git diff <commit1> <commit2>

Show changes introduced by going from commit1 to commit2.

git diff <commit1>...<commit2>

Show changes that would be applied if you were to merge commit2 to commit1.

git diff <path> [<path>...]

Only show changes that affect the given path(s).

git show <commit>

Show details of and changes introduced by the given commit.

git show <commit>:<path>

Show the content of the given path at the given commit.

Additional references

For when you need a little more help...

git help

Brief list of the most common commands.

git help git

Extensive list of commands and options to the "git" command itself.

git help tutorial[-2]

Two parts of a rapid tutorial introducing basic Git operations.

git help glossary

Glossary of common Git terms to use along with other documentation.

git help <command>

Detailed help on a particular Git command.

You can find a walk-through tutorial for Git on my blog: http://shotgunsandpenguins.blogspot.com/search/label/Git

Feel free to email me with comments or questions:

Ryan Stewart <rds6235@gmail.com>

This work is licensed under the Creative Commons Attribution-Share Alike 3.0 United States License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/us/ or send a letter to Creative Commons, 171 2nd Street, Suite 300, San Francisco, California, 94105, USA.

2 comments:

Daniel Lenski said...

This is a great cheat sheet!

I was dismayed to see that ScribD is now charging for PDF downloads, including of CC-licensed content such as this. Do you know of any other site hosting a PDF?

Ryan said...

@Daniel: I'm glad you've found it useful. I've updated the post with a link to the reference hosted on my google drive. It should be the same version that Scribd has. Let me know if it doesn't work for you.