From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Tue, 20 Nov 2007 22:28:01 GMT
Subject: Re: [PATCH] Improve documentation of git-filter-branch rev-list specification.
Message-ID: <Pine.LNX.4.64.0711202223150.27959@racer.site>
In-Reply-To: <877ikc3gzc.wl%cworth@cworth.org>

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