X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fuser-manual.txt;h=03736bbcd3ebfd5e1cbe6a006acb2b31411af527;hb=50cfde14531a5b354bbc3a070fe39c1ee86e2915;hp=be5a1f4c10dfcc7f80da51ac0ab1dcf8523d2e43;hpb=559e4d7a0d2e98e887ac93c78631d3eeef378716;p=git.git diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index be5a1f4c1..03736bbcd 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -398,7 +398,7 @@ 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 you it does in yours (assuming their repository has that commit at +that it does in yours (assuming their repository has that commit at all). Understanding history: commits, parents, and reachability @@ -425,8 +425,8 @@ if commit X is an ancestor of commit Y. Equivalently, you could say that Y is a descendent of X, or that there is a chain of parents leading from commit Y to commit X. -Undestanding history: History diagrams -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Understanding history: History diagrams +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We will sometimes represent git history using diagrams like the one below. Commits are shown as "o", and the links between them with @@ -617,7 +617,7 @@ 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 which is useful for finding the +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 @@ -692,7 +692,7 @@ Naming commits We have seen several ways of naming commits already: - - 40-hexdigit SHA1 id + - 40-hexdigit object name - branch name: refers to the commit at the head of the given branch - tag name: refers to the commit pointed to by the given tag @@ -705,7 +705,7 @@ gitlink:git-rev-parse[1] man page for the complete list of ways to name revisions. Some examples: ------------------------------------------------- -$ git show fb47ddb2 # the first few characters of the SHA1 id +$ git show fb47ddb2 # the first few characters of the object name # are usually enough to specify it uniquely $ git show HEAD^ # the parent of the HEAD commit $ git show HEAD^^ # the grandparent @@ -743,8 +743,8 @@ which refers to the other branch that we're merging in to the current branch. The gitlink:git-rev-parse[1] command is a low-level command that is -occasionally useful for translating some name for a commit to the SHA1 id for -that commit: +occasionally useful for translating some name for a commit to the object +name for that commit: ------------------------------------------------- $ git rev-parse origin @@ -806,7 +806,7 @@ display options. Note that git log starts with the most recent commit and works backwards through the parents; however, since git history can contain -multiple independant lines of development, the particular order that +multiple independent lines of development, the particular order that commits are listed in may be somewhat arbitrary. Generating diffs @@ -861,7 +861,7 @@ $ git diff origin..master will tell you whether the contents of the project are the same at the two branches; in theory, however, it's possible that the same project contents could have been arrived at by two different historical -routes. You could compare the SHA1 id's: +routes. You could compare the object names: ------------------------------------------------- $ git rev-list origin @@ -933,12 +933,38 @@ actually is an ancestor of v1.5.0-rc1. Alternatively, note that ------------------------------------------------- -$ git log v1.5.0-rc1..305db0fd +$ git log v1.5.0-rc1..e05db0fd ------------------------------------------------- -will produce empty output if and only if v1.5.0-rc1 includes 305db0fd, +will produce empty output if and only if v1.5.0-rc1 includes e05db0fd, because it outputs only commits that are not reachable from v1.5.0-rc1. +As yet another alternative, the gitlink: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 + +------------------------------------------------- +$ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2 +! [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if +available + ! [v1.5.0-rc0] GIT v1.5.0 preview + ! [v1.5.0-rc1] GIT v1.5.0-rc1 + ! [v1.5.0-rc2] GIT v1.5.0-rc2 +... +------------------------------------------------- + +then search for a line that looks 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. + + Developing with git =================== @@ -1049,7 +1075,7 @@ $ git commit ------------------------------------------------- and git will prompt you for a commit message and then create the new -commmit. Check to make sure it looks like what you expected with +commit. Check to make sure it looks like what you expected with ------------------------------------------------- $ git show @@ -1377,8 +1403,8 @@ Ensuring reliability Checking the repository for corruption ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The gitlink:git-fsck[1] command runs a number of self-consistency -checks on the repository, and reports on any problems. This may take some +The gitlink:git-fsck[1] command runs a number of self-consistency checks +on the repository, and reports on any problems. This may take some time. The most common warning by far is about "dangling" objects: ------------------------------------------------- @@ -1394,17 +1420,17 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f ... ------------------------------------------------- -Dangling objects are objects that are harmless, but also unnecessary; you can -remove them at any time with gitlink:git-prune[1] or the --prune option to -gitlink:git-gc[1]: +Dangling objects are objects that are harmless, but also unnecessary; +you can remove them at any time with gitlink:git-prune[1] or the --prune +option to gitlink:git-gc[1]: ------------------------------------------------- $ git gc --prune ------------------------------------------------- -This may be time-consuming. Unlike most other git operations (including git-gc -when run without any options), it is not safe to prune while other git -operations are in progress in the same repository. +This may be time-consuming. Unlike most other git operations (including +git-gc when run without any options), it is not safe to prune while +other git operations are in progress in the same repository. For more about dangling objects, see <>. @@ -1439,7 +1465,7 @@ $ gitk master@{"1 week ago"} # ... or last week ------------------------------------------------- The reflogs are kept by default for 30 days, after which they may be -pruned. See gitlink:git-reflink[1] and gitlink:git-gc[1] to learn +pruned. See gitlink:git-reflog[1] and gitlink:git-gc[1] to learn how to control this pruning, and see the "SPECIFYING REVISIONS" section of gitlink:git-rev-parse[1] for details. @@ -1466,7 +1492,7 @@ dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5 ... ------------------------------------------------- -and watch for output that mentions "dangling commits". You can examine +You can examine one of those dangling commits with, for example, ------------------------------------------------ @@ -1537,8 +1563,8 @@ repository that you pulled from. <>; instead, your branch will just be updated to point to the latest commit from the upstream branch). -The git-pull command can also be given "." as the "remote" repository, in -which case it just merges in a branch from the current repository; so +The git-pull command can also be given "." as the "remote" repository, +in which case it just merges in a branch from the current repository; so the commands ------------------------------------------------- @@ -1554,7 +1580,7 @@ Submitting patches to a project If you just have a few changes, the simplest way to submit them may just be to send them as patches in email: -First, use gitlink:git-format-patches[1]; for example: +First, use gitlink:git-format-patch[1]; for example: ------------------------------------------------- $ git format-patch origin @@ -1776,7 +1802,9 @@ set this up. Allow web browsing of a repository ---------------------------------- -TODO: Brief setup-instructions for gitweb +The gitweb cgi script provides users an easy way to browse your +project's files and history without having to install git; see the file +gitweb/README in the git source tree for instructions on setting it up. Examples -------- @@ -1784,11 +1812,6 @@ Examples TODO: topic branches, typical roles as in everyday.txt, ? -Working with other version control systems -========================================== - -TODO: CVS, Subversion, series-of-release-tarballs, etc. - [[cleaning-up-history]] Rewriting history and maintaining patch series ============================================== @@ -2645,13 +2668,13 @@ $ git-cat-file commit | head -1 since the tree object information is always the first line in a commit object. -Once you know the three trees you are going to merge (the one -"original" tree, aka the common case, and the two "result" trees, aka -the branches you want to merge), you do a "merge" read into the -index. This will complain if it has to throw away your old index contents, so you should +Once you know the three trees you are going to merge (the one "original" +tree, aka the common case, and the two "result" trees, aka the branches +you want to merge), you do a "merge" read into the index. This will +complain if it has to throw away your old index contents, so you should make sure that you've committed those - in fact you would normally -always do a merge against your last commit (which should thus match -what you have in your current index anyway). +always do a merge against your last commit (which should thus match what +you have in your current index anyway). To do the merge, do @@ -2732,7 +2755,7 @@ stages to temporary files and calls a "merge" script on it: $ git-merge-index git-merge-one-file hello.c ------------------------------------------------- -and that is what higher level `git resolve` is implemented with. +and that is what higher level `git merge -s resolve` is implemented with. How git stores objects efficiently: pack files ---------------------------------------------- @@ -2801,32 +2824,34 @@ Dangling objects The gitlink:git-fsck[1] command will sometimes complain about dangling objects. They are not a problem. -The most common cause of dangling objects is that you've rebased a branch, or -you have pulled from somebody else who rebased a branch--see -<>. In that case, the old head of the original branch -still exists, as does obviously everything it pointed to. The branch pointer -itself just doesn't, since you replaced it with another one. - -There are also other situations too that cause dangling objects. For example, a -"dangling blob" may arise because you did a "git add" of a file, but then, -before you actually committed it and made it part of the bigger picture, you -changed something else in that file and committed that *updated* thing - the -old state that you added originally ends up not being pointed to by any -commit or tree, so it's now a dangling blob object. - -Similarly, when the "recursive" merge strategy runs, and finds that there -are criss-cross merges and thus more than one merge base (which is fairly -unusual, but it does happen), it will generate one temporary midway tree -(or possibly even more, if you had lots of criss-crossing merges and -more than two merge bases) as a temporary internal merge base, and again, -those are real objects, but the end result will not end up pointing to -them, so they end up "dangling" in your repository. - -Generally, dangling objects aren't anything to worry about. They can even -be very useful: if you screw something up, the dangling objects can be how -you recover your old tree (say, you did a rebase, and realized that you -really didn't want to - you can look at what dangling objects you have, -and decide to reset your head to some old dangling state). +The most common cause of dangling objects is that you've rebased a +branch, or you have pulled from somebody else who rebased a branch--see +<>. In that case, the old head of the original +branch still exists, as does obviously everything it pointed to. The +branch pointer itself just doesn't, since you replaced it with another +one. + +There are also other situations too that cause dangling objects. For +example, a "dangling blob" may arise because you did a "git add" of a +file, but then, before you actually committed it and made it part of the +bigger picture, you changed something else in that file and committed +that *updated* thing - the old state that you added originally ends up +not being pointed to by any commit or tree, so it's now a dangling blob +object. + +Similarly, when the "recursive" merge strategy runs, and finds that +there are criss-cross merges and thus more than one merge base (which is +fairly unusual, but it does happen), it will generate one temporary +midway tree (or possibly even more, if you had lots of criss-crossing +merges and more than two merge bases) as a temporary internal merge +base, and again, those are real objects, but the end result will not end +up pointing to them, so they end up "dangling" in your repository. + +Generally, dangling objects aren't anything to worry about. They can +even be very useful: if you screw something up, the dangling objects can +be how you recover your old tree (say, you did a rebase, and realized +that you really didn't want to - you can look at what dangling objects +you have, and decide to reset your head to some old dangling state). For commits, the most useful thing to do with dangling objects tends to be to do a simple @@ -2835,23 +2860,24 @@ be to do a simple $ gitk --not --all ------------------------------------------------ -For blobs and trees, you can't do the same, but you can examine them. You -can just do +For blobs and trees, you can't do the same, but you can examine them. +You can just do ------------------------------------------------ $ git show ------------------------------------------------ -to show what the contents of the blob were (or, for a tree, basically what -the "ls" for that directory was), and that may give you some idea of what -the operation was that left that dangling object. +to show what the contents of the blob were (or, for a tree, basically +what the "ls" for that directory was), and that may give you some idea +of what the operation was that left that dangling object. -Usually, dangling blobs and trees aren't very interesting. They're almost -always the result of either being a half-way mergebase (the blob will -often even have the conflict markers from a merge in it, if you have had -conflicting merges that you fixed up by hand), or simply because you -interrupted a "git fetch" with ^C or something like that, leaving _some_ -of the new objects in the object database, but just dangling and useless. +Usually, dangling blobs and trees aren't very interesting. They're +almost always the result of either being a half-way mergebase (the blob +will often even have the conflict markers from a merge in it, if you +have had conflicting merges that you fixed up by hand), or simply +because you interrupted a "git fetch" with ^C or something like that, +leaving _some_ of the new objects in the object database, but just +dangling and useless. Anyway, once you are sure that you're not interested in any dangling state, you can just prune all unreachable objects: @@ -2860,9 +2886,9 @@ 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 -repository - it's kind of like doing a filesystem fsck recovery: you don't -want to do that while the filesystem is mounted. +and they'll be gone. But 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 @@ -2897,12 +2923,13 @@ Think about how to create a clear chapter dependency graph that will allow people to get to important topics without necessarily reading everything in between. +Say something about .gitignore. + Scan Documentation/ for other stuff left out; in particular: howto's - README some of technical/? hooks - etc. + list of commands in gitlink:git[1] Scan email archives for other stuff left out @@ -2923,6 +2950,12 @@ standard end-of-chapter section? Include cross-references to the glossary, where appropriate. -To document: - reflogs, git reflog expire - shallow clones?? See draft 1.5.0 release notes for some documentation. +Document shallow clones? See draft 1.5.0 release notes for some +documentation. + +Add a section on working with other version control systems, including +CVS, Subversion, and just imports of series of release tarballs. + +More details on gitweb? + +Write a chapter on using plumbing and writing scripts.