General note: All the stuff in all uppercase should probably also
have some asciidoc emphasis.
On Tue, Jul 03, 2007 at 05:47:44PM +0100, Johannes Schindelin wrote:
> +DESCRIPTION
> +-----------
> +Lets you rewrite git revision history by creating a new branch from
> +your current branch, 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 takes the new branch name as a mandatory argument and
> +the filters as optional arguments. If you specify no filters, the
> +commits will be recommitted without any changes, which would normally
> +have no effect and result in the new branch pointing to the same
> +branch as your current branch. Nevertheless, this may be useful in
> +the future for compensating for some git bugs or such, therefore
> +such a usage is permitted.
> +
> +WARNING! The rewritten history will have different object names for all
> +the objects and will not converge with the original branch. You will not
> +be able to easily push and distribute the rewritten branch on top of the
> +original branch. Please do not use this command if you do not know the
> +full implications, and avoid using it anyway, if a simple single commit
> +would suffice to fix your problem.
> +
> +Always verify that the rewritten version is correct before disposing
> +the original branch.
> +
> +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.
> +tmpfs. Reportedly the speedup is very noticeable.
> +
> +
> +Filters
> +~~~~~~~
> +
> +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"?
> +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?
> +A 'map' function is available that takes an "original sha1 id" argument
> +and outputs a "rewritten sha1 id" if the commit has been already
> +rewritten, fails otherwise; the 'map' function can return several
> +ids on separate lines if your commit filter emitted multiple commits.
> +
> +
> +OPTIONS
> +-------
> +
> +--env-filter <command>::
> + This is the filter for modifying the environment in which
> + the commit will be performed. Specifically, you might want
> + to rewrite the author/committer name/email/time environment
> + variables (see gitlink:git-commit[1] for details). Do not forget
> + to re-export the variables.
> +
> +--tree-filter <command>::
> + This is the filter for rewriting the tree and its contents.
> + The argument is evaluated in shell with the working
> + directory set to the root of the checked out tree. The new tree
> + 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"?
[...]
> +--subdirectory-filter <directory>::
> + Only regard the history, as seen by the given subdirectory. The
^^^
Does this comma belong there?
> + result will contain that directory as its project root.
> +
> +-d <directory>::
> + Use this option to set the path to the temporary directory used for
> + rewriting. When applying a tree filter, the command needs to
> + temporary checkout the tree to some directory, which may consume
> + considerable space in case of large projects. By default it
> + does this in the '.git-rewrite/' directory but you can override
> + that choice by this parameter.
> +
> +<rev-list-options>::
> + When options are given after the new branch name, they will
> + be passed to gitlink:git-rev-list[1]. Only commits in the resulting
> + output will be filtered, although the filtered commits can still
> + reference parents which are outside of that set.
> +
> +
> +Examples
> +--------
> +
> +Suppose you want to remove a file (containing confidential information
> +or copyright violation) from all commits:
> +
> +-------------------------------------------------------
> +git filter-branch --tree-filter 'rm filename' newbranch
> +-------------------------------------------------------
> +
> +A significantly faster version:
> +
> +-------------------------------------------------------------------------------
> +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.
> +
> +Now, you will get the rewritten history saved in the branch 'newbranch'
> +(your current branch is left untouched).
> +
> +To "etch-graft" a commit to the revision history (set a commit to be
> +the parent of the current initial commit and propagate that):
> +
> +----------------------------------------------------------------------
> +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.
> +(if the parent string is empty - therefore we are dealing with the
> +initial commit - add graftcommit as a parent). Note that this assumes
> +history with a single root (that is, no merge without common ancestors
> +happened). If this is not the case, use:
> +
[...]
Gruesse,
--
Frank Lichtenheld <frank@xxxxxxxxxxxxxx>
www: http://www.djpig.de/
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
