git-1.9.0.tar.gz

Git User Manual =============== Git is a fast distributed revision control system. This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of Git. <<repositories-and-branches>> and <<exploring-git-history>> explain how to fetch and study a project using git--read these chapters to learn how to build and test a particular version of a software project, search for regressions, and so on. People needing to do actual development will also want to read <<Developing-With-git>> and <<sharing-development>>. Further chapters cover more specialized topics. Comprehensive reference documentation is available through the man pages, or linkgit:git-help[1] command. For example, for the command `git clone <repo>`, you can either use: ------------------------------------------------ $ man git-clone ------------------------------------------------ or: ------------------------------------------------ $ git help clone ------------------------------------------------ With the latter, you can use the manual viewer of your choice; see linkgit:git-help[1] for more information. See also <<git-quick-start>> for a brief overview of Git commands, without any explanation. Finally, see <<todo>> for ways that you can help make this manual more complete. [[repositories-and-branches]] Repositories and Branches ========================= [[how-to-get-a-git-repository]] 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 linkgit:git-clone[1] command to download a copy of an existing repository. If you don't already have a project in mind, here are some interesting examples: ------------------------------------------------ # Git itself (approx. 40MB download): $ git clone git://git.kernel.org/pub/scm/git/git.git # the Linux kernel (approx. 640MB download): $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git ------------------------------------------------ The initial clone may be time-consuming for a large project, but you will only need to clone once. 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 <<def_working_tree,working tree>>, together with a special top-level directory named `.git`, which contains all the information about the history of the project. [[how-to-check-out]] 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. It stores the history as a compressed collection of interrelated snapshots of the project's contents. In Git each such version is called a <<def_commit,commit>>. Those snapshots aren't necessarily all arranged in a single line from oldest to newest; instead, work may simultaneously proceed along parallel lines of development, called <<def_branch,branches>>, which may merge and diverge. A single Git repository can track development on multiple branches. It does this by keeping a list of <<def_head,heads>> which reference the latest commit on each branch; the linkgit:git-branch[1] command shows you the list of branch heads: ------------------------------------------------ $ git branch * master ------------------------------------------------ A freshly cloned repository contains a single branch head, by default named "master", with the working directory initialized to the state of the project referred to by that branch head. Most projects also use <<def_tag,tags>>. Tags, like heads, are references into the project's history, and can be listed using the linkgit:git-tag[1] command: ------------------------------------------------ $ git tag -l v2.6.11 v2.6.11-tree v2.6.12 v2.6.12-rc2 v2.6.12-rc3 v2.6.12-rc4 v2.6.12-rc5 v2.6.12-rc6 v2.6.13 ... ------------------------------------------------ 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 linkgit:git-checkout[1]: ------------------------------------------------ $ git checkout -b new v2.6.13 ------------------------------------------------ The working directory then reflects the contents that the project had when it was tagged v2.6.13, and linkgit:git-branch[1] shows two branches, with an asterisk marking the currently checked-out branch: ------------------------------------------------ $ git branch master * new ------------------------------------------------ If you decide that you'd rather see version 2.6.17, you can modify the current branch to point at v2.6.17 instead, with ------------------------------------------------ $ git reset --hard v2.6.17 ------------------------------------------------ Note that if the current branch head was your only reference to a particular point in history, then resetting that branch may leave you with no way to find the history it used to point to; so use this command carefully. [[understanding-commits]] Understanding History: Commits ------------------------------ Every change in the history of a project is represented by a commit. The linkgit:git-show[1] command shows the most recent commit on the current branch: ------------------------------------------------ $ git show commit 17cf781661e6d38f737f15f53ab552f1e95960d7 Author: Linus Torvalds <torvalds@ppc970.osdl.org.(none)> Date: Tue Apr 19 14:11:06 2005 -0700 Remove duplicate getenv(DB_ENVIRONMENT) call Noted by Tony Luck. diff --git a/init-db.c b/init-db.c index 65898fa..b002dc6 100644 --- a/init-db.c +++ b/init-db.c @@ -7,7 +7,7 @@ int main(int argc, char **argv) { - char *sha1_dir = getenv(DB_ENVIRONMENT), *path; + char *sha1_dir, *path; int len, i; if (mkdir(".git", 0755) < 0) { ------------------------------------------------ As you can see, a commit shows who made the latest change, what they did, and why. Every commit has a 40-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: so if you tell somebody else the object name (for example in email), then you are guaranteed that name will refer to the same commit in their repository that it does in yours (assuming their repository has that commit at all). 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. [[understanding-reachability]] Understanding history: commits, parents, and reachability ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Every commit (except the very first commit in a project) also has a parent commit which shows what happened before this commit. 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 linkgit:gitk[1] command; running gitk now on a Git repository and looking for merge commits will help unders