diff options
Diffstat (limited to 'Documentation/git-filter-branch.txt')
| -rw-r--r-- | Documentation/git-filter-branch.txt | 81 |
1 files changed, 36 insertions, 45 deletions
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 020028c..81f5823 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -32,8 +32,9 @@ 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. -*NOTE*: This command honors `.git/info/grafts`. If you have any grafts -defined, running this command will make them permanent. +*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`. +If you have any grafts or replacement refs defined, running this command +will make them permanent. *WARNING*! The rewritten history will have different object names for all the objects and will not converge with the original branch. You will not @@ -81,7 +82,7 @@ OPTIONS This filter may be used if you only need to modify the environment in which the commit will be performed. Specifically, you might want to rewrite the author/committer name/email/time environment - variables (see linkgit:git-commit[1] for details). Do not forget + variables (see linkgit:git-commit-tree[1] for details). Do not forget to re-export the variables. --tree-filter <command>:: @@ -95,8 +96,8 @@ OPTIONS --index-filter <command>:: This is the filter for rewriting the index. It is similar to the tree filter but does not check out the tree, which makes it much - faster. Frequently used with `git rm \--cached - \--ignore-unmatch ...`, see EXAMPLES below. For hairy + faster. Frequently used with `git rm --cached + --ignore-unmatch ...`, see EXAMPLES below. For hairy cases, see linkgit:git-update-index[1]. --parent-filter <command>:: @@ -117,7 +118,7 @@ OPTIONS This is the filter for performing the commit. If this filter is specified, it will be called instead of the 'git commit-tree' command, with arguments of the form - "<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on + "<TREE_ID> [(-p <PARENT_COMMIT_ID>)...]" and the log message on stdin. The commit id is expected on stdout. + As a special extension, the commit filter may emit multiple @@ -159,18 +160,7 @@ to other tags will be rewritten to point to the underlying commit. --subdirectory-filter <directory>:: Only look at the history which touches the given subdirectory. The result will contain that directory (and only that) as its - project root. Implies --remap-to-ancestor. - ---remap-to-ancestor:: - Rewrite refs to the nearest rewritten ancestor instead of - ignoring them. -+ -Normally, positive refs on the command line are only changed if the -commit they point to was rewritten. However, you can limit the extent -of this rewriting by using linkgit:rev-list[1] arguments, e.g., path -limiters. Refs pointing to such excluded commits would then normally -be ignored. With this option, they are instead rewritten to point at -the nearest ancestor that was not excluded. + project root. Implies <<Remap_to_ancestor>>. --prune-empty:: Some kind of filters will generate empty commits, that left the tree @@ -204,7 +194,18 @@ the nearest ancestor that was not excluded. Arguments for 'git rev-list'. All positive refs included by these options are rewritten. You may also specify options such as '--all', but you must use '--' to separate them from - the 'git filter-branch' options. + the 'git filter-branch' options. Implies <<Remap_to_ancestor>>. + + +[[Remap_to_ancestor]] +Remap to ancestor +~~~~~~~~~~~~~~~~~ + +By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit the +set of revisions which get rewritten. However, positive refs on the command +line are distinguished: we don't let them be excluded by such limiters. For +this purpose, they are instead rewritten to point at the nearest ancestor that +was not excluded. Examples @@ -221,11 +222,11 @@ However, if the file is absent from the tree of some commit, a simple `rm filename` will fail for that tree and commit. Thus you may instead want to use `rm -f filename` as the script. -Using `\--index-filter` with 'git rm' yields a significantly faster +Using `--index-filter` with 'git rm' yields a significantly faster version. Like with using `rm filename`, `git rm --cached filename` will fail if the file is absent from the tree of a commit. If you want to "completely forget" a file, it does not matter when it entered -history, so we also add `\--ignore-unmatch`: +history, so we also add `--ignore-unmatch`: -------------------------------------------------------------------------- git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD @@ -241,8 +242,8 @@ git filter-branch --subdirectory-filter foodir -- --all ------------------------------------------------------- Thus you can, e.g., turn a library subdirectory into a repository of -its own. Note the `\--` that separates 'filter-branch' options from -revision options, and the `\--all` to rewrite all branches and tags. +its own. Note the `--` that separates 'filter-branch' options from +revision options, and the `--all` to rewrite all branches and tags. To set a commit (which typically is at the tip of another history) to be the parent of the current initial commit, in @@ -361,7 +362,7 @@ git filter-branch --index-filter \ 'git ls-files -s | sed "s-\t\"*-&newsubdir/-" | GIT_INDEX_FILE=$GIT_INDEX_FILE.new \ git update-index --index-info && - mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' HEAD + mv "$GIT_INDEX_FILE.new" "$GIT_INDEX_FILE"' HEAD --------------------------------------------------------------- @@ -370,23 +371,23 @@ Checklist for Shrinking a Repository ------------------------------------ git-filter-branch is often used to get rid of a subset of files, -usually with some combination of `\--index-filter` and -`\--subdirectory-filter`. People expect the resulting repository to +usually with some combination of `--index-filter` and +`--subdirectory-filter`. People expect the resulting repository to be smaller than the original, but you need a few more steps to actually make it smaller, because git tries hard not to lose your objects until you tell it to. First make sure that: * You really removed all variants of a filename, if a blob was moved - over its lifetime. `git log \--name-only \--follow \--all \-- - filename` can help you find renames. + over its lifetime. `git log --name-only --follow --all -- filename` + can help you find renames. -* You really filtered all refs: use `\--tag-name-filter cat \-- - \--all` when calling git-filter-branch. +* You really filtered all refs: use `--tag-name-filter cat -- --all` + when calling git-filter-branch. Then there are two ways to get a smaller repository. A safer way is to clone, that keeps your original intact. -* Clone it with `git clone +++file:///path/to/repo+++`. The clone +* Clone it with `git clone file:///path/to/repo`. The clone will not have the removed objects. See linkgit:git-clone[1]. (Note that cloning with a plain path just hardlinks everything!) @@ -396,24 +397,14 @@ approach, so *make a backup* or go back to cloning it. You have been warned. * Remove the original refs backed up by git-filter-branch: say `git - for-each-ref \--format="%(refname)" refs/original/ | xargs -n 1 git + for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git update-ref -d`. -* Expire all reflogs with `git reflog expire \--expire=now \--all`. +* Expire all reflogs with `git reflog expire --expire=now --all`. -* Garbage collect all unreferenced objects with `git gc \--prune=now` +* Garbage collect all unreferenced objects with `git gc --prune=now` (or if your git-gc is not new enough to support arguments to - `\--prune`, use `git repack -ad; git prune` instead). - - -Author ------- -Written by Petr "Pasky" Baudis <pasky@suse.cz>, -and the git list <git@vger.kernel.org> - -Documentation --------------- -Documentation by Petr Baudis and the git list. + `--prune`, use `git repack -ad; git prune` instead). GIT --- |