X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fuser-manual.txt;h=03736bbcd3ebfd5e1cbe6a006acb2b31411af527;hb=50cfde14531a5b354bbc3a070fe39c1ee86e2915;hp=87c605fad5a6df19d9f49b8f2bd7b106af95f388;hpb=b181d57ff40d94799a595045718039dc9d4320f7;p=git.git diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 87c605fad..03736bbcd 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -238,7 +238,7 @@ Repository maintenance Check for corruption: ----------------------------------------------- -$ git fsck-objects +$ git fsck ----------------------------------------------- Recompress, remove unused cruft: @@ -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 @@ -601,9 +601,10 @@ $ cat .git/config ... ------------------------------------------------- -This is what causes git to track the remote's branches; you may -modify or delete these configuration options by editing .git/config -with a text editor. +This is what causes git to track the remote's branches; you may modify +or delete these configuration options by editing .git/config with a +text editor. (See the "CONFIGURATION FILE" section of +gitlink:git-config[1] for details.) Exploring git history ===================== @@ -616,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 @@ -691,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 @@ -704,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 @@ -742,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 @@ -805,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 @@ -860,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 @@ -932,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 =================== @@ -955,6 +982,9 @@ $ cat >~/.gitconfig <<\EOF EOF ------------------------------------------------ +(See the "CONFIGURATION FILE" section of gitlink:git-config[1] for +details on the configuration file.) + Creating a new repository ------------------------- @@ -1045,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 @@ -1373,20 +1403,117 @@ Ensuring reliability Checking the repository for corruption ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -TODO: - git-fsck - "dangling objects" explanation - Brief explanation here, - include forward reference to longer explanation from - Linus, to be added to later chapter +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: + +------------------------------------------------- +$ git fsck +dangling commit 7281251ddd2a61e38657c827739c57015671a6b3 +dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63 +dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5 +dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb +dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f +dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e +dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085 +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]: + +------------------------------------------------- +$ 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. + +For more about dangling objects, see <>. + Recovering lost changes ~~~~~~~~~~~~~~~~~~~~~~~ -TODO: - reflog - git-fsck - low-level examination of objects +Reflogs +^^^^^^^ + +Say you modify a branch with gitlink:git-reset[1] --hard, and then +realize that the branch was the only reference you had to that point in +history. + +Fortunately, git also keeps a log, called a "reflog", of all the +previous values of each branch. So in this case you can still find the +old history using, for example, + +------------------------------------------------- +$ git log master@{1} +------------------------------------------------- + +This lists the commits reachable from the previous version of the head. +This syntax can be used to with any git command that accepts a commit, +not just with git log. Some other examples: + +------------------------------------------------- +$ git show master@{2} # See where the branch pointed 2, +$ git show master@{3} # 3, ... changes ago. +$ gitk master@{yesterday} # See where it pointed yesterday, +$ 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-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. + +Note that the reflog history is very different from normal git history. +While normal history is shared by every repository that works on the +same project, the reflog history is not shared: it tells you only about +how the branches in your local repository have changed over time. + +Examining dangling objects +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In some situations the reflog may not be able to save you. For +example, suppose you delete a branch, then realize you need the history +it pointed you. The reflog is also deleted; however, if you have not +yet pruned the repository, then you may still be able to find +the lost commits; run git-fsck and watch for output that mentions +"dangling commits": + +------------------------------------------------- +$ git fsck +dangling commit 7281251ddd2a61e38657c827739c57015671a6b3 +dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63 +dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5 +... +------------------------------------------------- + +You can examine +one of those dangling commits with, for example, + +------------------------------------------------ +$ gitk 7281251ddd --not --all +------------------------------------------------ + +which does what it sounds like: it says that you want to see the commit +history that is described by the dangling commit(s), but not the +history that is described by all your existing branches and tags. Thus +you get exactly the history reachable from that commit that is lost. +(And notice that it might not be just one commit: we only report the +"tip of the line" as being dangling, but there might be a whole deep +and complex commit history that was gotten dropped.) + +If you decide you want the history back, you can always create a new +reference pointing to it, for example, a new branch: + +------------------------------------------------ +$ git branch recovered-branch 7281251ddd +------------------------------------------------ + Sharing development with others =============================== @@ -1425,7 +1552,7 @@ $ git pull ------------------------------------------------- See the descriptions of the branch..remote and -branch..merge options in gitlink:git-repo-config[1] to learn +branch..merge options in gitlink:git-config[1] to learn how to control these defaults depending on the current branch. In addition to saving you keystrokes, "git pull" also helps you by @@ -1436,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 ------------------------------------------------- @@ -1453,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 @@ -1660,7 +1787,7 @@ $ git push public-repo master ------------------------------------------------- See the explanations of the remote..url, branch..remote, -and remote..push options in gitlink:git-repo-config[1] for +and remote..push options in gitlink:git-config[1] for details. Setting up a shared repository @@ -1675,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 -------- @@ -1683,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 ============================================== @@ -1974,10 +2098,10 @@ Configuring remote branches We saw above that "origin" is just a shortcut to refer to the repository which you originally cloned from. This information is stored in git configuration variables, which you can see using -gitlink:git-repo-config[1]: +gitlink:git-config[1]: ------------------------------------------------- -$ git-repo-config -l +$ git config -l core.repositoryformatversion=0 core.filemode=true core.logallrefupdates=true @@ -1992,7 +2116,7 @@ create similar configuration options to save typing; for example, after ------------------------------------------------- -$ git repo-config remote.example.url git://example.com/proj.git +$ git config remote.example.url git://example.com/proj.git ------------------------------------------------- then the following two commands will do the same thing: @@ -2005,7 +2129,7 @@ $ git fetch example master:refs/remotes/example/master Even better, if you add one more option: ------------------------------------------------- -$ git repo-config remote.example.fetch master:refs/remotes/example/master +$ git config remote.example.fetch master:refs/remotes/example/master ------------------------------------------------- then the following commands will all do the same thing: @@ -2020,7 +2144,7 @@ $ git fetch example You can also add a "+" to force the update each time: ------------------------------------------------- -$ git repo-config remote.example.fetch +master:ref/remotes/example/master +$ git config remote.example.fetch +master:ref/remotes/example/master ------------------------------------------------- Don't do this unless you're sure you won't mind "git fetch" possibly @@ -2028,9 +2152,9 @@ throwing away commits on mybranch. Also note that all of the above configuration can be performed by directly editing the file .git/config instead of using -gitlink:git-repo-config[1]. +gitlink:git-config[1]. -See gitlink:git-repo-config[1] for more details on the configuration +See gitlink:git-config[1] for more details on the configuration options mentioned above. @@ -2101,7 +2225,7 @@ size> + + . The structured objects can further have their structure and connectivity to other objects verified. This is generally done with -the `git-fsck-objects` program, which generates a full dependency graph +the `git-fsck` program, which generates a full dependency graph of all objects, and verifies their internal consistency (in addition to just verifying their superficial consistency through the hash). @@ -2544,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 @@ -2631,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 ---------------------------------------------- @@ -2693,6 +2817,87 @@ objects will work exactly as they did before. The gitlink:git-gc[1] command performs packing, pruning, and more for you, so is normally the only high-level command you need. +[[dangling-objects]] +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). + +For commits, the most useful thing to do with dangling objects tends to +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 + +------------------------------------------------ +$ 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. + +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: + +------------------------------------------------ +$ 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. + +(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). + Glossary of git terms ===================== @@ -2718,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 @@ -2744,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.