This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of Git. People needing to do actual development will also want to read Developing with Git and Sharing development with others. Further chapters cover more specialized topics. Comprehensive reference documentation is available through the man pages, or git-help command.
See also Appendix A: Git Quick Reference for a brief overview of Git commands, without any explanation. Finally, see Appendix B: Notes and todo list for this manual for ways that you can help make this manual more complete. Repositories and Branches How to get a Git repository It will be useful to have a Git repository to experiment with as you read this manual. The best way to get one is by using the git-clone command to download a copy of an existing repository.
The clone command creates a new directory named after the project git or linux in the examples above. After you cd into this directory, you will see that it contains a copy of the project files, called the working tree , together with a special top-level directory named.
How to check out a different version of a project Git is best thought of as a tool for storing the history of a collection of files. In Git each such version is called a commit. A single Git repository can track development on multiple branches. It does this by keeping a list of heads which reference the latest commit on each branch; the git-branch command shows you the list of branch heads: Most projects also use tags.
Tags are expected to always point at the same version of a project, while heads are expected to advance as development progresses. Create a new branch head pointing to one of these versions and check it out using git-checkout: Commits Every change in the history of a project is represented by a commit. The git-show command shows the most recent commit on the current branch: Tue Apr 19 Every commit has a hexdigit id, sometimes called the "object name" or the "SHA-1 id", shown on the first line of the git show output.
You can usually refer to a commit by a shorter name, such as a tag or a branch name, but this longer name can also be useful. Most importantly, it is a globally unique name for this commit: Since the object name is computed as a hash over the contents of the commit, you are guaranteed that the commit can never change without its name also changing. In fact, in Git concepts we shall see that everything stored in Git history, including file data and directory contents, is stored in an object with a name that is a hash of its contents.
Following the chain of parents will eventually take you back to the beginning of the project. However, the commits do not form a simple list; Git allows lines of development to diverge and then reconverge, and the point where two lines of development reconverge is called a "merge". The commit representing a merge can therefore have more than one parent, with each parent representing the most recent commit on one of the lines of development leading to that point.
The best way to see how this works is using the gitk command; running gitk now on a Git repository and looking for merge commits will help understand how Git organizes history. In the following, we say that commit X is "reachable" from commit Y if commit X is an ancestor of commit Y.
Equivalently, you could say that Y is a descendant of X, or that there is a chain of parents leading from commit Y to commit X. History diagrams We will sometimes represent Git history using diagrams like the one below.
Time goes left to right: What is a branch? When we need to be precise, we will use the word "branch" to mean a line of development, and "branch head" or just "head" to mean a reference to the most recent commit on a branch. In the example above, the branch head named "A" is a pointer to one particular commit, but we refer to the line of three commits leading up to that point as all being part of "branch A".
However, when no confusion will result, we often just use the term "branch" both for branches and for branch heads. The special symbol "HEAD" can always be used to refer to the current branch. You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this state without impacting any branches by performing another checkout. If you want to create a new branch to retain commits you create, you may do so now or later by using -b with the checkout command again.
This is an easy way to check out a particular version without having to make up a name for the new branch. You can still create a new branch or tag for this version later if you decide to. Examining branches from a remote repository The "master" branch that was created at the time you cloned is a copy of the HEAD in the repository that you cloned from.
That repository may also have had other branches, though, and your local repository keeps branches which track each of those remote branches, called remote-tracking branches, which you can view using the -r option to git-branch: The branches of this repository are called "remote branches" from our point of view.
The remote-tracking branches listed above were created based on the remote branches at clone time and will be updated by git fetch hence git pull and git push.
See Updating a repository with git fetch for details. You might want to build on one of these remote-tracking branches on a branch of your own, just as you would for a tag: Note that the name "origin" is just the name that Git uses by default to refer to the repository that you cloned from.
Naming branches, tags, and other references Branches, remote-tracking branches, and tags are all references to commits. The full name is occasionally useful if, for example, there ever exists a tag and a branch with the same name. Newly created refs are actually stored in the. However, for efficiency reasons they may also be packed together in a single file; see git-pack-refs. As another useful shortcut, the "HEAD" of a repository can be referred to just using the name of that repository.
So, for example, "origin" is usually a shortcut for the HEAD branch in the repository "origin". Updating a repository with git fetch After you clone a repository and commit a few changes of your own, you may wish to check the original repository for updates. The git-fetch command, with no arguments, will update all of the remote-tracking branches to the latest version found in the original repository. Fetching branches from other repositories You can also track branches from repositories other than the one you cloned from, using git-remote: If you examine the file.
Exploring Git history Git is best thought of as a tool for storing the history of a collection of files. It does this by storing compressed snapshots of the contents of a file hierarchy, together with "commits" which show the relationships between these snapshots. Git provides extremely flexible and fast tools for exploring the history of a project.
We start with one specialized tool that is useful for finding the commit that introduced a bug into a project. How to use bisect to find a regression Suppose version 2. The git-bisect command can help you do this: HEAD is now detached from any branch and points directly to a commit with commit id that is reachable from "master" but not from v2.
Compile and test it, and see whether it crashes. Assume it does crash. Drop useless bitmaskings checks out an older version. Continue like this, telling Git at each stage whether the version it gives you is good or bad, and notice that the number of revisions left to test is cut approximately in half each time. After about 13 tests in this case , it will output the commit id of the guilty commit.
You can then examine the commit with git-show , find out who wrote it, and mail them your bug report with the commit id. Choose a safe-looking commit nearby, note its commit id, and check it out with: Instead of git bisect visualize and then git reset --hard fb47ddb2db, you might just want to tell Git that you want to skip the current commit: There are also ways to automate the bisecting process if you have a test script that can tell a good from a bad commit.
See git-bisect for more information about this and other git bisect features. Naming commits We have seen several ways of naming commits already: The git-rev-parse command is a low-level command that is occasionally useful for translating some name for a commit to the object name for that commit: This creates a "lightweight" tag. If you would also like to include a comment with the tag, and possibly sign it cryptographically, then you should create a tag object instead; see the git-tag man page for details.
Browsing revisions The git-log command can show lists of commits. On its own, it shows all commits reachable from the parent commit; but you can also make more specific requests: Note that git log starts with the most recent commit and works backwards through the parents; however, since Git history can contain multiple independent lines of development, the particular order that commits are listed in may be somewhat arbitrary.
Generating diffs You can generate diffs between any two versions using git-diff: Viewing old file versions You can always view an old version of a file by just checking out the correct revision first. But sometimes it is more convenient to be able to view an old version of a single file without checking anything out; this command does that: You could compare the object names: Find first tagged version including a given fix Suppose you know that the commit e05db0fd fixed a certain problem. You could just visually inspect the commits since e05db0fd: If you just want to verify whether a given tagged version contains a given commit, you could use git-merge-base: As yet another alternative, the git-show-branch command lists the commits reachable from its arguments with a display on the left-hand side that indicates which arguments that commit is reachable from.
Showing commits unique to a given branch Suppose you would like to see all the commits reachable from the branch head named master but not from any other head in your repository. We can list all the heads in this repository with git-show-ref: Creating a changelog and tarball for a software release The git-archive command can create a tar or zip archive from any version of a project; for example: The output file format is inferred from the output file extension if possible, see git-archive for details.
Versions of Git older than 1.