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

From: Johannes Sixt <j6t@kdbg.org>
Date: Apr 27, 2011, 20:32 UTC
Message-ID: <4DB87D40.9090302@kdbg.org>
In-Reply-To: <1303927684-6513-2-git-send-email-michael.ocleirigh@rivulet.ca>

I like the example, particularly because it shows that it is not necessary to start off with index's content in an --index-filter, and that the index can be replaced with read-tree -i, i.e., GIT_INDEX_FILE juggling is not necessary for some tasks.

Am 27.04.2011 20:08, schrieb Michael O'Cleirigh:

> 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.

Sign-off is missing. Please keep lines well below 75 characters. Write 'Add an example...' rather than 'Added an example...'.

Show 28 quoted lines

> ---
>  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
>  -------------------------------------------------------------------

This places the new text in the middle of another example, doesn't it?

The prefered style of examples to give motivation first, then the example command, then a description of command details. I would drop the sentence "i.e. ... was reoranized... history" because it does not add value for the reader (I can think of other equally or even more likely reason why the interesting path structure is irregular).

The example looks better when it is broken into more lines, e.g. like this:

-----------------------------------------------------------
git filter-branch --prune-empty --index-filter '
		git ls-tree $GIT_COMMIT |
		egrep "(top-dir-A|top-dir-B|other-dir-C)" |
 		git mktree | xargs git read-tree -i -m'
-----------------------------------------------------------

And the dash lines are just as long as necessary.

-- Hannes