Re: [PATCH] Improve documentation of git-filter-branch rev-list specification.
From: Johannes Schindelin <hidden>
Date: 2016-06-15 22:43:52
Hi, On Tue, 20 Nov 2007, Carl Worth wrote:
quoted hunk ↗ jump to hunk
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