[PATCH] Documentation: pruning recipe for destructive filter-branch

[Thomas Rast <trast@student.ethz.ch>]

Add a section about how to shrink a repository's size after running
git-filter-branch to remove large blobs from history.

This comes up every week or so on IRC, and the commands required to
handle every case are not very newbie-friendly, so hopefully writing
them down somewhere leads to fewer questions.

Thanks to doener (Björn Steinbrink) for comments and corrections.

Signed-off-by: Thomas Rast <trast@student.ethz.ch>
---

Or we could just add an option --prune-everything-I-have-a-backup-I-promise
to git-filter-branch, so that users can get the same result with less effort.


 Documentation/git-filter-branch.txt |   36 +++++++++++++++++++++++++++++++++++
 1 files changed, 36 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index 1fbbbb4..737c555 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -339,6 +339,42 @@ git filter-branch --index-filter \
 ---------------------------------------------------------------
 
 
+
+Checklist for Shrinking a Repository
+------------------------------------
+
+git-filter-branch is often used to get rid of a subset of files,
+usually with some combination of `\--index-filter` and
+`\--subdirectory-filter`.  If you want to physically shrink the
+repository afterwards, you have some choices:
+
+* Clone it with `git clone file:///path/to/repo`.  The clone will not
+  have the removed objects.  See linkgit:git-clone[1].  (Note that
+  cloning with a plain path just hardlinks everything!)
+
+If you really don't want to clone it, for whatever reasons, check the
+following points (in this order).  This is a very destructive
+approach, so *make a backup* or go back to cloning it.  You have been
+warned.
+
+* Make sure you really removed all variants of a filename, if a blob
+  was moved over its lifetime.  `git log \--follow \--all \-- foo` can
+  help you find renames.
+
+* Make sure you really filtered all refs: use `\--tag-name-filter cat
+  \-- \--all` when calling git-filter-branch.
+
+* Make sure you remove the original refs backed up by
+  git-filter-branch: say `git for-each-ref \--format="%(refname)"
+  refs/original/ | xargs -n 1 git update-ref -d`.
+
+* Expire all reflogs with `git reflog expire \--expire=now \--all`.
+
+* Repack to remove packed objects with `git repack -ad`.
+
+* Prune unpacked unreferenced objects with `git prune \--expire=now`.
+
+
 Author
 ------
 Written by Petr "Pasky" Baudis <pasky@suse.cz>,
-- 
1.6.2.rc0.274.g97213