Hi Junio, It looks like my patch to documentation has been lost. I sent it about a week ago, and there has been no feedback to it, so I believe it is okay. The --prune option for 'git gc' was one of those options that you need to use from time to time, but it was perceived by many users as dangerous and many users were completely unaware of it, thus often it was not used as intended. Johannes' patch removed this option, which IMHO was a significant user interface improvement. Unfortunately, there are still a few places in the documentation where this option is mentioned. One of them is "Everyday GIT", which is intended for beginners. I believe it is very confusing for anyone who starts to use GIT to see an undocumented option among recommended practice. So, please, consider this patch for inclusion or provide any feedback as to what kind of improvements may be needed for its inclusion. Thanks, Dmitry -- >8 -- From: Dmitry Potapov <dpotapov@xxxxxxxxx> Date: Mon, 14 Apr 2008 15:52:00 +0400 Subject: [PATCH] Documentation: git-gc --prune is deprecated 25ee9731c137d0a24b0f4879eb0b0cce9b77d5b0 made the '--prune' option deprecated and removed its description from the git-gc man page. This patch removes all references to this option from the rest of the Git documentation. --- Documentation/everyday.txt | 6 ++---- Documentation/git-clone.txt | 10 ++++++---- Documentation/user-manual.txt | 17 +---------------- 3 files changed, 9 insertions(+), 24 deletions(-) diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt index fdbd15a..e598cdd 100644 --- a/Documentation/everyday.txt +++ b/Documentation/everyday.txt @@ -48,14 +48,12 @@ $ git gc <3> repository health reasonably well. <2> check how many loose objects there are and how much disk space is wasted by not repacking. -<3> repacks the local repository and performs other housekeeping tasks. Running -without `--prune` is a safe operation even while other ones are in progress. +<3> repacks the local repository and performs other housekeeping tasks. Repack a small project into single pack.:: + ------------ $ git gc <1> -$ git gc --prune ------------ + <1> pack all the objects reachable from the refs into one pack, @@ -182,7 +180,7 @@ $ git pull <3> $ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <4> $ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5> $ git reset --hard ORIG_HEAD <6> -$ git gc --prune <7> +$ git gc <7> $ git fetch --tags <8> ------------ + diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 9758243..c1bf814 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -65,10 +65,12 @@ OPTIONS + *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand what it does. If you clone your -repository using this option, then delete branches in the -source repository and then run linkgit:git-gc[1] using the -'--prune' option in the source repository, it may remove -objects which are referenced by the cloned repository. +repository using this option and then delete a branch or use +any other git command that makes any previous existing commit +unreachable, then after some time linkgit:git-gc[1] may remove +unreachable objects, and this will break the cloned repository. +Because some git commands may run git-gc, it may happen at any +time after gc.pruneExpire time since commits became unreachable. diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 565aeb9..86b91a5 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1548,22 +1548,7 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f Dangling objects are not a problem. At worst they may take up a little extra disk space. They can sometimes provide a last-resort method for -recovering lost work--see <<dangling-objects>> for details. However, if -you wish, you can remove them with linkgit:git-prune[1] or the `--prune` -option to linkgit: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. - -If linkgit: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 -<<recovering-from-repository-corruption>> for a detailed discussion. +recovering lost work--see <<dangling-objects>> for details. [[recovering-lost-changes]] Recovering lost changes -- 1.5.5 -- -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
