[PATCH 1/1] Documentation/git-filter-branch: add --index-filter example

[Michael O'Cleirigh <michael.ocleirigh@rivulet.ca>]

Added an example using git ls-tree on the $GIT_COMMIT and then filtering
what should remain in the history using egrep.

This allows multiple paths accross history to be retained when filtering a branch.
---
 Documentation/git-filter-branch.txt |   13 +++++++++++++
 1 files changed, 13 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index 9dc1f2a..e80bc01 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -248,6 +248,19 @@ To set a commit (which typically is at the tip of another
 history) to be the parent of the current initial commit, in
 order to paste the other history behind the current history:
 
+-----------------------------------------------------------------------------------------------------------------------------------
+git filter-branch --prune-empty --index-filter 'git ls-tree $GIT_COMMIT | egrep \
+"(top-dir-A|top-dir-B|consolidated-dir-C)" | git mktree | xargs git read-tree -i -m'
+-----------------------------------------------------------------------------------------------------------------------------------
+
+The --subdirectory-filter works great when all commits of interest have
+that path but sometimes you have a history that contains an irregular 
+structure. i.e. that was reorganized at some point and you would like to 
+keep the prior history.
+
+For each commit the top-dir-A, top-dir-B and consolidated-dir-C paths (if they exist)
+are kept (and everything else discarded). 
+
 -------------------------------------------------------------------
 git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
 -------------------------------------------------------------------
-- 
1.7.2.3