[PATCH] Improve documentation of git-filter-branch rev-list specification.

[PATCH] Improve documentation of git-filter-branch rev-list specification.

[Carl Worth]

The rev-list is not optional, and a range of a..b will not rewrite
only b. Fix these errors and improve the wording of surrounding text.

Also eliminate the discussion of using no filters to compensate for
hypothetical future bugs. It's not helpful.
---
 Documentation/git-filter-branch.txt |   34 ++++++++++++++++++++--------------
 1 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index ba9b4fb..985d7d5 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -13,23 +13,29 @@ SYNOPSIS
 	[--msg-filter <command>] [--commit-filter <command>]
 	[--tag-name-filter <command>] [--subdirectory-filter <directory>]
 	[--original <namespace>] [-d <directory>] [-f | --force]
-	[<rev-list options>...]
+	<rev-list options>...
 
 DESCRIPTION
 -----------
-Lets you rewrite git revision history by rewriting the branches mentioned
-in the <rev-list options>, applying custom filters on each revision.
-Those filters can modify each tree (e.g. removing a file or running
-a perl rewrite on all files) or information about each commit.
-Otherwise, all information (including original commit times or merge
-information) will be preserved.
-
-The command will only rewrite the _positive_ refs mentioned in the
-command line (i.e. if you pass 'a..b', only 'b' will be rewritten).
-If you specify no filters, the commits will be recommitted without any
-changes, which would normally have no effect.  Nevertheless, this may be
-useful in the future for compensating for some git bugs or such,
-therefore such a usage is permitted.
+Rewrites git revision history by applying one or more filters to a set
+of commits. The set of commits to be rewritten is supplied in
+<rev-list options> and can be as simple as one or more branch names,
+(in which case all commits reachable from those branch names will be
+rewritten).
+
+The filters can modify the tree content stored in each commit,
+(e.g. removing a file or running a perl rewrite on all files), or the
+associated information about each commit, (commit message, author,
+parent, etc.). Any information not affected by a filter (including
+original commit times or merge information) will be preserved. If you
+specify no filters, the commits will be recommitted without any
+changes.
+
+Note that passing a range of commits specified with the a..b notation
+will rewrite 'b' and all commits reachable from 'b' but not reachable
+from 'a', but will not rewrite the commit 'a' itself. This is
+consistent with the handling of a range by git-log and other git
+commands.
 
 *WARNING*! The rewritten history will have different object names for all
 the objects and will not converge with the original branch.  You will not
-- 
1.5.3.4

Ideas for improving the filter-branch workflow

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 2555 bytes --]

On Tue, 20 Nov 2007 10:32:39 -0800, Carl Worth wrote:
> The rev-list is not optional, and a range of a..b will not rewrite
> only b.

It has since been explained to me that the original text was intended
to describe which branch tips will get updated. In that case, my
rewrite of the documentation leaves that part out.

Even so, I'm a bit confused by what the behavior is. When I run:

	git filter-branch HEAD

The output I get is:

	Ref 'refs/heads/master' was rewritten

	These refs were rewritten:

And nothing else after that. That's definitely confusing.

Also confusing is that the documentation emphasizes that I should
verify the newly rewritten heads against the backups in
refs/original. But I'm not given any guidance on how to access the
refs in refs/original. I don't know of standard git tools to list
these, ("git branch", "git branch -r", and "gitk --all" don't show
them for example). I can use something like "git log
original/refs/heads/master" but it takes a fair amount of knowledge to
get to that point.

Finally, I did my filter in multiple steps and found myself having to
do lots of manual cleanup. For example, on my second run of
git-filter-branch:

	Error:		Namespace refs/original/ not empty
	Cleanup:	rm -r .git/refs/original

And that failed attempt then triggers another problem:

	Error:		.git-rewrite already exists, please remove it
	Cleanup:	rm -r .git-rewrite

The second error was nice enough to tell me how to fix the problem,
(nothing ever indicates the need to cleanup refs/original that I can
tell). But I think this second error should never occur. The
filter-branch program should cleanup after itself if it fails.

Finally, I wonder if there's a better solution to the messiness of
making backups in refs/original, correctly documenting what branch
heads get rewritten, and then hoping that the user can find the
backups, use them to verify the new heads, and then clean them up.

One idea is to have two new sub-commands for git-filter-branch. Maybe
something like:

	git filter-branch --accept
	git filter-branch --reject	# or --undo or whatever

And these would do all the cleanup necessary.

During the intermediate state, (after filter-branch and before
"filter-branch --accept"), it would be nice if it were easier to
verify the results. For example, if filter-branch stored its backups
in refs/heads/rewrite-original/* instead of refs/original/refs/heads/*
then they would show up automatically in "gitk --all" for example.

Anyway, those are some ideas if anyone wants to hack on this further.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [PATCH] Improve documentation of git-filter-branch rev-list specification.

[Johannes Schindelin]

Hi,

On Tue, 20 Nov 2007, Carl Worth wrote:

> diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
> index ba9b4fb..985d7d5 100644
> --- a/Documentation/git-filter-branch.txt
> +++ b/Documentation/git-filter-branch.txt
> @@ -13,23 +13,29 @@ SYNOPSIS
>  	[--msg-filter <command>] [--commit-filter <command>]
>  	[--tag-name-filter <command>] [--subdirectory-filter <directory>]
>  	[--original <namespace>] [-d <directory>] [-f | --force]
> -	[<rev-list options>...]
> +	<rev-list options>...

This is correct AFAICT.

>  DESCRIPTION
>  -----------
> -Lets you rewrite git revision history by rewriting the branches mentioned
> -in the <rev-list options>, applying custom filters on each revision.
> -Those filters can modify each tree (e.g. removing a file or running
> -a perl rewrite on all files) or information about each commit.
> -Otherwise, all information (including original commit times or merge
> -information) will be preserved.
> -
> -The command will only rewrite the _positive_ refs mentioned in the
> -command line (i.e. if you pass 'a..b', only 'b' will be rewritten).
> -If you specify no filters, the commits will be recommitted without any
> -changes, which would normally have no effect.  Nevertheless, this may be
> -useful in the future for compensating for some git bugs or such,
> -therefore such a usage is permitted.
> +Rewrites git revision history by applying one or more filters to a set
> +of commits. The set of commits to be rewritten is supplied in
> +<rev-list options> and can be as simple as one or more branch names,
> +(in which case all commits reachable from those branch names will be
> +rewritten).

I do not particularly like that you say "commits to be rewritten".  
Because not the commits, but the branches are rewritten.  For example, if 
you have branch A and B pointing to the same commit and you call 
filter-branch on A, B will be left untouched _along with its commits_.

IMHO the old version -- while maybe not as eloquent as yours -- made that 
very clear.

This was probably the reason you confused the comment about a..b earlier.

So I would appreciate rewriting the documentation in such a way that the 
distinction between a commit and a ref is maintained clearly.

Ciao,
Dscho

Re: [PATCH] Improve documentation of git-filter-branch rev-list specification.

[Johannes Sixt]

Carl Worth schrieb:
> +The filters can modify the tree content stored in each commit,
> +(e.g. removing a file or running a perl rewrite on all files), or the
> +associated information about each commit, (commit message, author,
> +parent, etc.). Any information not affected by a filter (including
> +original commit times or merge information) will be preserved. If you
> +specify no filters, the commits will be recommitted without any
> +changes.

"... will be recommitted without any changes as long as no grafted parents 
are encountered. Any grafted parents will be written into the commits even 
if no filters are specified."

-- Hannes