diff options
Diffstat (limited to 'Documentation/user-manual.txt')
| -rw-r--r-- | Documentation/user-manual.txt | 205 |
1 files changed, 98 insertions, 107 deletions
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index e831cc2020..cbb01a1ea2 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1,6 +1,5 @@ -Git User's Manual (for version 1.5.3 or newer) -______________________________________________ - +Git User Manual +_______________ Git is a fast distributed revision control system. @@ -57,17 +56,17 @@ 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. 10MB download): + # Git itself (approx. 40MB download): $ git clone git://git.kernel.org/pub/scm/git/git.git - # the Linux kernel (approx. 150MB download): -$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.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-2.6` in the examples above). After you cd into this +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 @@ -220,7 +219,7 @@ 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 understand how the Git organizes history. +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 @@ -269,27 +268,23 @@ Creating, deleting, and modifying branches is quick and easy; here's a summary of the commands: `git branch`:: - list all branches + list all branches. `git branch <branch>`:: create a new branch named `<branch>`, referencing the same - point in history as the current branch + point in history as the current branch. `git branch <branch> <start-point>`:: create a new branch named `<branch>`, referencing `<start-point>`, which may be specified any way you like, - including using a branch name or a tag name + including using a branch name or a tag name. `git branch -d <branch>`:: - delete the branch `<branch>`; if the branch you are deleting - points to a commit which is not reachable from the current - branch, this command will fail with a warning. + delete the branch `<branch>`; if the branch is not fully + merged in its upstream branch or contained in the current branch, + this command will fail with a warning. `git branch -D <branch>`:: - even if the branch points to a commit not reachable - from the current branch, you may know that that commit - is still reachable from some other branch or tag. In that - case it is safe to use this command to force Git to delete - the branch. + delete the branch `<branch>` irrespective of its merged status. `git checkout <branch>`:: make the current branch `<branch>`, updating the working - directory to reflect the version referenced by `<branch>` + directory to reflect the version referenced by `<branch>`. `git checkout -b <new> <start-point>`:: create a new branch `<new>` referencing `<start-point>`, and check it out. @@ -313,10 +308,17 @@ referenced by a tag: ------------------------------------------------ $ git checkout v2.6.17 -Note: moving to "v2.6.17" which isn't a local branch -If you want to create a new branch from this checkout, you may do so -(now or later) by using -b with the checkout command again. Example: - git checkout -b <new_branch_name> +Note: checking out 'v2.6.17'. + +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. Example: + + git checkout -b new_branch_name + HEAD is now at 427abfa... Linux v2.6.17 ------------------------------------------------ @@ -327,7 +329,7 @@ and git branch shows that you are no longer on a branch: $ cat .git/HEAD 427abfa28afedffadfca9dd8b067eb6d36bac53f $ git branch -* (no branch) +* (detached from v2.6.17) master ------------------------------------------------ @@ -431,19 +433,25 @@ You can also track branches from repositories other than the one you cloned from, using linkgit:git-remote[1]: ------------------------------------------------- -$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git -$ git fetch linux-nfs -* refs/remotes/linux-nfs/master: storing branch 'master' ... - commit: bf81b46 +$ git remote add staging git://git.kernel.org/.../gregkh/staging.git +$ git fetch staging +... +From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging + * [new branch] master -> staging/master + * [new branch] staging-linus -> staging/staging-linus + * [new branch] staging-next -> staging/staging-next ------------------------------------------------- New remote-tracking branches will be stored under the shorthand name -that you gave `git remote add`, in this case `linux-nfs`: +that you gave `git remote add`, in this case `staging`: ------------------------------------------------- $ git branch -r -linux-nfs/master -origin/master + origin/HEAD -> origin/master + origin/master + staging/master + staging/staging-linus + staging/staging-next ------------------------------------------------- If you run `git fetch <remote>` later, the remote-tracking branches @@ -455,9 +463,9 @@ a new stanza: ------------------------------------------------- $ cat .git/config ... -[remote "linux-nfs"] - url = git://linux-nfs.org/pub/nfs-2.6.git - fetch = +refs/heads/*:refs/remotes/linux-nfs/* +[remote "staging"] + url = git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git + fetch = +refs/heads/*:refs/remotes/staging/* ... ------------------------------------------------- @@ -781,7 +789,7 @@ e05db0fd4f31dde7005f075a84f96b360d05984b ------------------------------------------------- Or you could recall that the `...` operator selects all commits -contained reachable from either one reference or the other but not +reachable from either one reference or the other but not both; so ------------------------------------------------- @@ -808,7 +816,7 @@ You could just visually inspect the commits since e05db0fd: $ gitk e05db0fd.. ------------------------------------------------- -Or you can use linkgit:git-name-rev[1], which will give the commit a +or you can use linkgit:git-name-rev[1], which will give the commit a name based on any tag it finds pointing to one of the commit's descendants: @@ -852,8 +860,8 @@ because it outputs only commits that are not reachable from v1.5.0-rc1. As yet another alternative, the linkgit:git-show-branch[1] 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. So, -you can run something like +side that indicates which arguments that commit is reachable from. +So, if you run something like ------------------------------------------------- $ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2 @@ -865,15 +873,15 @@ available ... ------------------------------------------------- -then search for a line that looks like +then a line like ------------------------------------------------- + ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if available ------------------------------------------------- -Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and -from v1.5.0-rc2, but not from v1.5.0-rc0. +shows that e05db0fd is reachable from itself, from v1.5.0-rc1, +and from v1.5.0-rc2, and not from v1.5.0-rc0. [[showing-commits-unique-to-a-branch]] Showing commits unique to a given branch @@ -1068,19 +1076,13 @@ produce no output at that point. Modifying the index is easy: -To update the index with the new contents of a modified file, use +To update the index with the contents of a new or modified file, use ------------------------------------------------- $ git add path/to/file ------------------------------------------------- -To add the contents of a new file to the index, use - -------------------------------------------------- -$ git add path/to/file -------------------------------------------------- - -To remove a file from the index and from the working tree, +To remove a file from the index and from the working tree, use ------------------------------------------------- $ git rm path/to/file @@ -1781,7 +1783,7 @@ $ git pull . branch $ git merge branch ------------------------------------------------- -are roughly equivalent. The former is actually very commonly used. +are roughly equivalent. [[submitting-patches]] Submitting patches to a project @@ -1835,7 +1837,7 @@ Once the index is updated with the results of the conflict resolution, instead of creating a new commit, just run ------------------------------------------------- -$ git am --resolved +$ git am --continue ------------------------------------------------- and Git will create the commit for you and continue applying the @@ -1971,7 +1973,7 @@ $ git clone http://yourserver.com/~you/proj.git ------------------------------------------------- (See also -link:howto/setup-git-server-over-http.txt[setup-git-server-over-http] +link:howto/setup-git-server-over-http.html[setup-git-server-over-http] for a slightly more sophisticated setup using WebDAV which also allows pushing over HTTP.) @@ -2156,7 +2158,7 @@ To set this up, first create your work tree by cloning Linus's public tree: ------------------------------------------------- -$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work +$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git work $ cd work ------------------------------------------------- @@ -2198,7 +2200,7 @@ make it easy to push both branches to your public tree. (See ------------------------------------------------- $ cat >> .git/config <<EOF [remote "mytree"] - url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git + url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux.git push = release push = test EOF @@ -2243,11 +2245,11 @@ commit to this branch. $ ... patch ... test ... commit [ ... patch ... test ... commit ]* ------------------------------------------------- -When you are happy with the state of this change, you can pull it into the +When you are happy with the state of this change, you can merge it into the "test" branch in preparation to make it public: ------------------------------------------------- -$ git checkout test && git pull . speed-up-spinlocks +$ git checkout test && git merge speed-up-spinlocks ------------------------------------------------- It is unlikely that you would have any conflicts here ... but you might if you @@ -2259,7 +2261,7 @@ see the value of keeping each patch (or patch series) in its own branch. It means that the patches can be moved into the `release` tree in any order. ------------------------------------------------- -$ git checkout release && git pull . speed-up-spinlocks +$ git checkout release && git merge speed-up-spinlocks ------------------------------------------------- After a while, you will have a number of branches, and despite the @@ -3185,23 +3187,21 @@ those "loose" objects. You can save space and make Git faster by moving these loose objects in to a "pack file", which stores a group of objects in an efficient compressed format; the details of how pack files are formatted can be -found in link:technical/pack-format.txt[technical/pack-format.txt]. +found in link:technical/pack-format.html[pack format]. To put the loose objects into a pack, just run git repack: ------------------------------------------------ $ git repack -Generating pack... -Done counting 6020 objects. -Deltifying 6020 objects. - 100% (6020/6020) done -Writing 6020 objects. - 100% (6020/6020) done -Total 6020, written 6020 (delta 4070), reused 0 (delta 0) -Pack pack-3e54ad29d5b2e05838c75df582c65257b8d08e1c created. +Counting objects: 6020, done. +Delta compression using up to 4 threads. +Compressing objects: 100% (6020/6020), done. +Writing objects: 100% (6020/6020), done. +Total 6020 (delta 4070), reused 0 (delta 0) ------------------------------------------------ -You can then run +This creates a single "pack file" in .git/objects/pack/ +containing all currently unpacked objects. You can then run ------------------------------------------------ $ git prune @@ -3299,17 +3299,11 @@ state, you can just prune all unreachable objects: $ git prune ------------------------------------------------ -and they'll be gone. But you should only run `git prune` on a quiescent +and they'll be gone. (You should only run `git prune` on a quiescent repository--it's kind of like doing a filesystem fsck recovery: you don't want to do that while the filesystem is mounted. - -(The same is true of `git fsck` itself, btw, but since -`git fsck` never actually *changes* the repository, it just reports -on what it found, `git fsck` itself is never 'dangerous' to run. -Running it while somebody is actually changing the repository can cause -confusing and scary messages, but it won't actually do anything bad. In -contrast, running `git prune` while somebody is actively changing the -repository is a *BAD* idea). +`git prune` is designed not to cause any harm in such cases of concurrent +accesses to a repository but you might receive confusing or scary messages.) [[recovering-from-repository-corruption]] Recovering from repository corruption @@ -3532,7 +3526,7 @@ with Git 1.5.2 can look up the submodule commits in the repository and manually check them out; earlier versions won't recognize the submodules at all. -To see how submodule support works, create (for example) four example +To see how submodule support works, create four example repositories that can be used later as a submodule: ------------------------------------------------- @@ -3634,7 +3628,7 @@ working on a branch. ------------------------------------------------- $ git branch -* (no branch) +* (detached from d266b98) master ------------------------------------------------- @@ -3904,7 +3898,7 @@ fact that such a commit brings together ("merges") two or more previous states represented by other commits. In other words, while a "tree" represents a particular directory state -of a working directory, a "commit" represents that state in "time", +of a working directory, a "commit" represents that state in time, and explains how we got there. You create a commit object by giving it the tree that describes the @@ -3924,8 +3918,7 @@ save the note about that state, in practice we tend to just write the result to the file pointed at by `.git/HEAD`, so that we can always see what the last committed state was. -Here is an ASCII art by Jon Loeliger that illustrates how -various pieces fit together. +Here is a picture that illustrates how various pieces fit together: ------------ @@ -4004,27 +3997,26 @@ to see what the top commit was. Merging multiple trees ---------------------- -Git helps you do a three-way merge, which you can expand to n-way by -repeating the merge procedure arbitrary times until you finally -"commit" the state. The normal situation is that you'd only do one -three-way merge (two parents), and commit it, but if you like to, you -can do multiple parents in one go. +Git can help you perform a three-way merge, which can in turn be +used for a many-way merge by repeating the merge procedure several +times. The usual situation is that you only do one three-way merge +(reconciling two lines of history) and commit the result, but if +you like to, you can merge several branches in one go. -To do a three-way merge, you need the two sets of "commit" objects -that you want to merge, use those to find the closest common parent (a -third "commit" object), and then use those commit objects to find the -state of the directory ("tree" object) at these points. +To perform a three-way merge, you start with the two commits you +want to merge, find their closest common parent (a third commit), +and compare the trees corresponding to these three commits. -To get the "base" for the merge, you first look up the common parent -of two commits with +To get the "base" for the merge, look up the common parent of two +commits: ------------------------------------------------- $ git merge-base <commit1> <commit2> ------------------------------------------------- -which will return you the commit they are both based on. You should -now look up the "tree" objects of those commits, which you can easily -do with (for example) +This prints the name of a commit they are both based on. You should +now look up the tree objects of those commits, which you can easily +do with ------------------------------------------------- $ git cat-file commit <commitname> | head -1 @@ -4146,8 +4138,6 @@ about the data in the object. It's worth noting that the SHA-1 hash that is used to name the object is the hash of the original data plus this header, so `sha1sum` 'file' does not match the object name for 'file'. -(Historical note: in the dawn of the age of Git the hash -was the SHA-1 of the 'compressed' object.) As a result, the general consistency of an object can always be tested independently of the contents or the type of the object: all objects can @@ -4256,15 +4246,16 @@ no longer need to call `setup_pager()` directly). Nowadays, `git log` is a builtin, which means that it is _contained_ in the command `git`. The source side of a builtin is -- a function called `cmd_<bla>`, typically defined in `builtin-<bla>.c`, - and declared in `builtin.h`, +- a function called `cmd_<bla>`, typically defined in `builtin/<bla.c>` + (note that older versions of Git used to have it in `builtin-<bla>.c` + instead), and declared in `builtin.h`. - an entry in the `commands[]` array in `git.c`, and - an entry in `BUILTIN_OBJECTS` in the `Makefile`. Sometimes, more than one builtin is contained in one source file. For -example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin-log.c`, +example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin/log.c`, since they share quite a bit of code. In that case, the commands which are _not_ named like the `.c` file in which they live have to be listed in `BUILT_INS` in the `Makefile`. @@ -4287,10 +4278,10 @@ For the sake of clarity, let's stay with `git cat-file`, because it - is plumbing, and - was around even in the initial commit (it literally went only through - some 20 revisions as `cat-file.c`, was renamed to `builtin-cat-file.c` + some 20 revisions as `cat-file.c`, was renamed to `builtin/cat-file.c` when made a builtin, and then saw less than 10 versions). -So, look into `builtin-cat-file.c`, search for `cmd_cat_file()` and look what +So, look into `builtin/cat-file.c`, search for `cmd_cat_file()` and look what it does. ------------------------------------------------------------------ @@ -4366,7 +4357,7 @@ Another example: Find out what to do in order to make some script a builtin: ------------------------------------------------- -$ git log --no-merges --diff-filter=A builtin-*.c +$ git log --no-merges --diff-filter=A builtin/*.c ------------------------------------------------- You see, Git is actually the best tool to find out about the source of Git @@ -4668,5 +4659,5 @@ Write a chapter on using plumbing and writing scripts. Alternates, clone -reference, etc. More on recovery from repository corruption. See: - http://marc.theaimsgroup.com/?l=git&m=117263864820799&w=2 - http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2 + http://marc.info/?l=git&m=117263864820799&w=2 + http://marc.info/?l=git&m=117147855503798&w=2 |