Re: [PATCH] Document git-filter-branch

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Jul 3, 2007, 23:17 UTC
Message-ID: <Pine.LNX.4.64.0707040004200.4071@racer.site>
In-Reply-To: <20070703220540.GN12721@planck.djpig.de>

Hi,

[if you comment on just a small portion of the text, could you please quote only that? Thank you]

On Wed, 4 Jul 2007, Frank Lichtenheld wrote:

> General note: All the stuff in all uppercase should probably also
> have some asciidoc emphasis.

I do not understand. I grepped through all the docs for uppercase words emphasized in any way, and could not find one.

Show 6 quoted lines

> On Tue, Jul 03, 2007 at 05:47:44PM +0100, Johannes Schindelin wrote:
>
> > +Note that since this operation is extensively I/O expensive, it might
> > +be a good idea to redirect the temporary directory it off-disk, e.g. on
>                                                     ^^^^^^
> The "it" probably doesn't belong there.

Right.

Show 6 quoted lines

> > +The filters are applied in the order as listed below.  The <command>
> > +argument is always evaluated in shell using the 'eval' command.
> > +The $GIT_COMMIT environment variable is permanently set to contain
>                                            ^^^^^^^^^^^
> I find the use of this word in this context odd and a little confusing.
> Maybe better "always" or "each time"?

How about

	Prior to that, the $GIT_COMMIT environment variable will be set to 
	contain the id of the commit being rewritten.

> > +the id of the commit being rewritten.  The author/committer environment
> > +variables are set before the first filter is run.
> 
> Maybe give the actual names of the environment variables here?

If you think so:

	Also, GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, 
	GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, and GIT_COMMITTER_DATE is 
	set according to the current commit.

Show 5 quoted lines

> > +	is then used as-is (new files are auto-added, disappeared files
> > +	are auto-removed - .gitignore files nor any other ignore rules
> > +	HAVE NO EFFECT!).
> 
> Is "nor" correct here? Not just "or"?

Do you like

	neither .gitignore files nor any other ignore rules HAVE ANY 
	EFFECT!

Show 5 quoted lines

> [...]
> > +--subdirectory-filter <directory>::
> > +	Only regard the history, as seen by the given subdirectory. The
>                               ^^^
> Does this comma belong there?

This is my bad English. What I meant was this:

        Only ever look at the history, which touches the given 
	subdirectory.  The result will contain that directory as its 
	project root.

Show 7 quoted lines

> > +-------------------------------------------------------------------------------
> > +git filter-branch --index-filter 'git update-index --remove filename' newbranch
> > +-------------------------------------------------------------------------------
> 
> Even if your code goes beyond 80 chars, the surrounding "---" doesn't
> have to and makes it even harder to read when reading the original
> asciidoc text.

I personally read the .txt files, and use asciidoc only when I am forced to. So it makes a difference for me.

Show 8 quoted lines

> > +----------------------------------------------------------------------
> > +git filter-branch --parent-filter sed\ 's/^$/-p <graft-id>/' newbranch
> > +----------------------------------------------------------------------
> 
> Wouldn't have 'sed s/^$/-p <graft-id>/' exactly the same effect, since
> the quotes are interpreted by the original shell anyway and not the
> filter shell? Just wondering why it uses such a complicated way to
> express it.

Probably not. Since the shell would interpret "s/^$/-p" and "<graft-id>/" as two arguments to sed.

Besides, like Pasky, I am used to quote the argument, and not the whole line, that's why the line is still there as it is.

Thanks, Dscho