From f0c4881facabc0aa76f4b51871bd70c45effb508 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 25 Nov 2007 10:34:27 -0800 Subject: git-checkout: describe detached head correctly When you have a file called HEAD in the work tree, the code to report where the HEAD is at when "git checkout $commit^0" is done triggered unnecessary ambiguity checking. Explicitly mark the command line with "--" and make it clear that we are talking about a revision. Signed-off-by: Junio C Hamano diff --git a/git-checkout.sh b/git-checkout.sh index 17f4392..5ca7124 100755 --- a/git-checkout.sh +++ b/git-checkout.sh @@ -169,7 +169,7 @@ detach_warn= describe_detached_head () { test -n "$quiet" || { printf >&2 "$1 " - GIT_PAGER= git log >&2 -1 --pretty=oneline --abbrev-commit "$2" + GIT_PAGER= git log >&2 -1 --pretty=oneline --abbrev-commit "$2" -- } } -- cgit v0.10.2-6-g49f6 From 0c4a33b54f3dbb9fa8cd2f5cf0e2a6363849d899 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sun, 25 Nov 2007 13:53:37 -0500 Subject: user-manual: define "branch" and "working tree" at start Some explanation here might help. Signed-off-by: J. Bruce Fields diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index c027353..8355cce 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -56,11 +56,12 @@ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.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-2.6" in the examples above). After you cd into this directory, you will see that it contains a copy of the project files, -together with a special top-level directory named ".git", which -contains all the information about the history of the project. +called the <>, 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 @@ -71,8 +72,13 @@ 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 <>. -A single git repository may contain multiple branches. It keeps track -of them by keeping a list of <> which reference the +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 >, which may +merge and diverge. + +A single git repository can track development on multiple branches. It +does this by keeping a list of <> which reference the latest commit on each branch; the gitlink:git-branch[1] command shows you the list of branch heads: -- cgit v0.10.2-6-g49f6 From 81eb417ad423ef7e8d088d517f89d3bda92f9c06 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sun, 25 Nov 2007 17:54:19 -0500 Subject: user-manual: failed push to public repository More details on the case of a failed push to a public (non-shared) repository. Signed-off-by: J. Bruce Fields diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 8355cce..547c936 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1929,15 +1929,9 @@ or just $ git push ssh://yourserver.com/~you/proj.git master ------------------------------------------------- -As with git-fetch, git-push will complain if this does not result in -a <>. Normally this is a sign of -something wrong. However, if you are sure you know what you're -doing, you may force git-push to perform the update anyway by -proceeding the branch name by a plus sign: - -------------------------------------------------- -$ git push ssh://yourserver.com/~you/proj.git +master -------------------------------------------------- +As with git-fetch, git-push will complain if this does not result in a +<>; see the following section for details on +handling this case. Note that the target of a "push" is normally a <> repository. You can also push to a @@ -1965,6 +1959,52 @@ See the explanations of the remote..url, branch..remote, and remote..push options in gitlink:git-config[1] for details. +[[forcing-push]] +What to do when a push fails +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If a push would not result in a <> of the +remote branch, then it will fail with an error like: + +------------------------------------------------- +error: remote 'refs/heads/master' is not an ancestor of + local 'refs/heads/master'. + Maybe you are not up-to-date and need to pull first? +error: failed to push to 'ssh://yourserver.com/~you/proj.git' +------------------------------------------------- + +This can happen, for example, if you: + + - use `git reset --hard` to remove already-published commits, or + - use `git commit --amend` to replace already-published commits + (as in <>), or + - use `git rebase` to rebase any already-published commits (as + in <>). + +You may force git-push to perform the update anyway by preceding the +branch name with a plus sign: + +------------------------------------------------- +$ git push ssh://yourserver.com/~you/proj.git +master +------------------------------------------------- + +Normally whenever a branch head in a public repository is modified, it +is modified to point to a descendent of the commit that it pointed to +before. By forcing a push in this situation, you break that convention. +(See <>.) + +Nevertheless, this is a common practice for people that need a simple +way to publish a work-in-progress patch series, and it is an acceptable +compromise as long as you warn other developers that this is how you +intend to manage the branch. + +It's also possible for a push to fail in this way when other people have +the right to push to the same repository. In that case, the correct +solution is to retry the push after first updating your work by either a +pull or a fetch followed by a rebase; see the +<> and +link:cvs-migration.html[git for CVS users] for more. + [[setting-up-a-shared-repository]] Setting up a shared repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v0.10.2-6-g49f6 From 7cb192eab0251911e2ca77d4ecceb621dd2d34f5 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sun, 25 Nov 2007 19:01:57 -0500 Subject: user-manual: clarify language about "modifying" old commits It's important to remember that git doesn't really allowing "editing" or "modifying" commits, only replacing them by new commits. Redo some of the language to make this clearer. Signed-off-by: J. Bruce Fields diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 547c936..7fd3791 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1416,8 +1416,8 @@ with the changes to be reverted, then you will be asked to fix conflicts manually, just as in the case of <>. -[[fixing-a-mistake-by-editing-history]] -Fixing a mistake by editing history +[[fixing-a-mistake-by-rewriting-history]] +Fixing a mistake by rewriting history ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the problematic commit is the most recent commit, and you have not @@ -1440,7 +1440,7 @@ Again, you should never do this to a commit that may already have been merged into another branch; use gitlink:git-revert[1] instead in that case. -It is also possible to edit commits further back in the history, but +It is also possible to replace commits further back in the history, but this is an advanced topic to be left for <>. @@ -1977,7 +1977,7 @@ This can happen, for example, if you: - use `git reset --hard` to remove already-published commits, or - use `git commit --amend` to replace already-published commits - (as in <>), or + (as in <>), or - use `git rebase` to rebase any already-published commits (as in <>). @@ -2472,11 +2472,11 @@ return mywork to the state it had before you started the rebase: $ git rebase --abort ------------------------------------------------- -[[modifying-one-commit]] -Modifying a single commit +[[rewriting-one-commit]] +Rewriting a single commit ------------------------- -We saw in <> that you can replace the +We saw in <> that you can replace the most recent commit using ------------------------------------------------- @@ -2486,8 +2486,10 @@ $ git commit --amend which will replace the old commit by a new commit incorporating your changes, giving you a chance to edit the old commit message first. -You can also use a combination of this and gitlink:git-rebase[1] to edit -commits further back in your history. First, tag the problematic commit with +You can also use a combination of this and gitlink:git-rebase[1] to +replace a commit further back in your history and recreate the +intervening changes on top of it. First, tag the problematic commit +with ------------------------------------------------- $ git tag bad mywork~5 -- cgit v0.10.2-6-g49f6 From 1cdade2c4cb27f648a98d326ef3db523b6afafa7 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sat, 3 Mar 2007 22:53:37 -0500 Subject: user-manual: recovering from corruption Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre with a little further editing by me. Signed-off-by: "J. Bruce Fields" diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 7fd3791..b0a873b 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1560,6 +1560,11 @@ 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. +If gitlink:git-fsck[1] complains about sha1 mismatches or missing +objects, you may have a much more serious problem; your best option is +probably restoring from backups. See +<> for a detailed discussion. + [[recovering-lost-changes]] Recovering lost changes ~~~~~~~~~~~~~~~~~~~~~~~ @@ -3220,6 +3225,127 @@ 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). +[[recovering-from-repository-corruption]] +Recovering from repository corruption +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By design, git treats data trusted to it with caution. However, even in +the absence of bugs in git itself, it is still possible that hardware or +operating system errors could corrupt data. + +The first defense against such problems is backups. You can back up a +git directory using clone, or just using cp, tar, or any other backup +mechanism. + +As a last resort, you can search for the corrupted objects and attempt +to replace them by hand. Back up your repository before attempting this +in case you corrupt things even more in the process. + +We'll assume that the problem is a single missing or corrupted blob, +which is sometimes a solveable problem. (Recovering missing trees and +especially commits is *much* harder). + +Before starting, verify that there is corruption, and figure out where +it is with gitlink:git-fsck[1]; this may be time-consuming. + +Assume the output looks like this: + +------------------------------------------------ +$ git-fsck --full +broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 + to blob 4b9458b3786228369c63936db65827de3cc06200 +missing blob 4b9458b3786228369c63936db65827de3cc06200 +------------------------------------------------ + +(Typically there will be some "dangling object" messages too, but they +aren't interesting.) + +Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6 +points to it. If you could find just one copy of that missing blob +object, possibly in some other repository, you could move it into +.git/objects/4b/9458b3... and be done. Suppose you can't. You can +still examine the tree that pointed to it with gitlink:git-ls-tree[1], +which might output something like: + +------------------------------------------------ +$ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 +100644 blob 8d14531846b95bfa3564b58ccfb7913a034323b8 .gitignore +100644 blob ebf9bf84da0aab5ed944264a5db2a65fe3a3e883 .mailmap +100644 blob ca442d313d86dc67e0a2e5d584b465bd382cbf5c COPYING +... +100644 blob 4b9458b3786228369c63936db65827de3cc06200 myfile +... +------------------------------------------------ + +So now you know that the missing blob was the data for a file named +"myfile". And chances are you can also identify the directory--let's +say it's in "somedirectory". If you're lucky the missing copy might be +the same as the copy you have checked out in your working tree at +"somedirectory/myfile"; you can test whether that's right with +gitlink:git-hash-object[1]: + +------------------------------------------------ +$ git hash-object -w somedirectory/myfile +------------------------------------------------ + +which will create and store a blob object with the contents of +somedirectory/myfile, and output the sha1 of that object. if you're +extremely lucky it might be 4b9458b3786228369c63936db65827de3cc06200, in +which case you've guessed right, and the corruption is fixed! + +Otherwise, you need more information. How do you tell which version of +the file has been lost? + +The easiest way to do this is with: + +------------------------------------------------ +$ git log --raw --all --full-history -- somedirectory/myfile +------------------------------------------------ + +Because you're asking for raw output, you'll now get something like + +------------------------------------------------ +commit abc +Author: +Date: +... +:100644 100644 4b9458b... newsha... M somedirectory/myfile + + +commit xyz +Author: +Date: + +... +:100644 100644 oldsha... 4b9458b... M somedirectory/myfile +------------------------------------------------ + +This tells you that the immediately preceding version of the file was +"newsha", and that the immediately following version was "oldsha". +You also know the commit messages that went with the change from oldsha +to 4b9458b and with the change from 4b9458b to newsha. + +If you've been committing small enough changes, you may now have a good +shot at reconstructing the contents of the in-between state 4b9458b. + +If you can do that, you can now recreate the missing object with + +------------------------------------------------ +$ git hash-object -w +------------------------------------------------ + +and your repository is good again! + +(Btw, you could have ignored the fsck, and started with doing a + +------------------------------------------------ +$ git log --raw --all +------------------------------------------------ + +and just looked for the sha of the missing object (4b9458b..) in that +whole thing. It's up to you - git does *have* a lot of information, it is +just missing one particular blob version. + [[the-index]] The index ----------- @@ -4429,4 +4555,7 @@ Write a chapter on using plumbing and writing scripts. Alternates, clone -reference, etc. -git unpack-objects -r for recovery +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.theaimsgroup.com/?l=git&m=117147855503798&w=2 -- cgit v0.10.2-6-g49f6