1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns=
"http://www.w3.org/1999/xhtml" xml:
lang=
"en">
5 <meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8" />
6 <meta name=
"generator" content=
"AsciiDoc 8.4.5" />
7 <title>git-filter-branch(
1)
</title>
8 <style type=
"text/css">
10 p
, li
, dt
, dd
, div
, pre
, h1
, h2
, h3
, h4
, h5
, h6
{
12 border: 1px solid red;
17 margin: 1em 5% 1em 5%;
22 text-decoration: underline
;
42 h1
, h2
, h3
, h4
, h5
, h6
{
44 font-family: sans-serif
;
51 border-bottom: 2px solid silver
;
69 border: 1px solid silver
;
88 font-family: sans-serif
;
94 span#revnumber
, span#revdate
, span#revremark
{
95 font-family: sans-serif
;
99 font-family: sans-serif
;
101 border-top: 2px solid silver
;
107 padding-bottom: 0.5em;
111 padding-bottom: 0.5em;
116 margin-bottom: 1.5em;
118 div
.tableblock
, div
.imageblock
, div
.exampleblock
, div
.verseblock
,
119 div
.quoteblock
, div
.literalblock
, div
.listingblock
, div
.sidebarblock
,
120 div
.admonitionblock
{
122 margin-bottom: 1.5em;
124 div
.admonitionblock
{
126 margin-bottom: 2.5em;
129 div
.content
{ /* Block element content. */
133 /* Block element titles. */
134 div
.title
, caption
.title
{
136 font-family: sans-serif
;
140 margin-bottom: 0.5em;
146 td div
.title:first-child
{
149 div
.content div
.title:first-child
{
152 div
.content
+ div
.title
{
156 div
.sidebarblock
> div
.content
{
158 border: 1px solid silver
;
162 div
.listingblock
> div
.content
{
163 border: 1px solid silver
;
172 div
.quoteblock
> div
.attribution
{
181 div
.verseblock
> div
.content
{
184 div
.verseblock
> div
.attribution
{
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
189 div
.verseblock
+ div
.attribution
{
193 div
.admonitionblock
.icon
{
197 text-decoration: underline
;
199 padding-right: 0.5em;
201 div
.admonitionblock td
.content
{
203 border-left: 2px solid silver
;
206 div
.exampleblock
> div
.content
{
207 border-left: 2px solid silver
;
211 div
.imageblock div
.content
{ padding-left: 0; }
212 span
.image img
{ border-style: none
; }
213 a
.image:visited
{ color: white
; }
217 margin-bottom: 0.8em;
230 list-style-position: outside
;
233 list-style-type: decimal
;
236 list-style-type: lower-alpha
;
239 list-style-type: upper-alpha
;
242 list-style-type: lower-roman
;
245 list-style-type: upper-roman
;
248 div
.compact ul
, div
.compact ol
,
249 div
.compact p
, div
.compact p
,
250 div
.compact div
, div
.compact div
{
252 margin-bottom: 0.1em;
255 div
.tableblock
> table
{
256 border: 3px solid
#527bbd;
259 font-family: sans-serif
;
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
272 div
.tableblock
> table
[frame
="void"] {
275 div
.tableblock
> table
[frame
="hsides"] {
276 border-left-style: none
;
277 border-right-style: none
;
279 div
.tableblock
> table
[frame
="vsides"] {
280 border-top-style: none
;
281 border-bottom-style: none
;
287 margin-bottom: 0.8em;
290 padding-bottom: 15px;
292 dt
.hdlist1
.strong
, td
.hdlist1
.strong
{
298 padding-right: 0.8em;
304 div
.hdlist
.compact tr
{
314 div#footer-badges
{ display: none
; }
319 font-family: sans-serif
;
323 margin-bottom: 0.1em;
326 div
.toclevel1
, div
.toclevel2
, div
.toclevel3
, div
.toclevel4
{
342 /* Overrides for manpage documents */
345 padding-bottom: 0.5em;
346 border-top: 2px solid silver
;
347 border-bottom: 2px solid silver
;
357 div#toc
{ display: none
; }
360 /* Workarounds for IE6's broken and incomplete CSS2. */
362 div
.sidebar-content
{
364 border: 1px solid silver
;
367 div
.sidebar-title
, div
.image-title
{
369 font-family: sans-serif
;
372 margin-bottom: 0.5em;
375 div
.listingblock div
.content
{
376 border: 1px solid silver
;
381 div
.quoteblock-attribution
{
386 div
.verseblock-content
{
389 div
.verseblock-attribution
{
394 div
.exampleblock-content
{
395 border-left: 2px solid silver
;
399 /* IE6 sets dynamically generated links as visited. */
400 div#toc
a:visited
{ color: blue
; }
406 git-filter-branch(
1) Manual Page
409 <div class=
"sectionbody">
410 <p>git-filter-branch -
415 <h2 id=
"_synopsis">SYNOPSIS
</h2>
416 <div class=
"sectionbody">
417 <div class=
"verseblock">
418 <div class=
"verseblock-content"><em>git filter-branch
</em> [--env-filter
<command
>] [--tree-filter
<command
>]
419 [--index-filter
<command
>] [--parent-filter
<command
>]
420 [--msg-filter
<command
>] [--commit-filter
<command
>]
421 [--tag-name-filter
<command
>] [--subdirectory-filter
<directory
>]
423 [--original
<namespace
>] [-d
<directory
>] [-f | --force]
424 [--] [
<rev-list options
>…]
</div>
425 <div class=
"verseblock-attribution">
428 <h2 id=
"_description">DESCRIPTION
</h2>
429 <div class=
"sectionbody">
430 <div class=
"paragraph"><p>Lets you rewrite git revision history by rewriting the branches mentioned
431 in the
<rev-list options
>, applying custom filters on each revision.
432 Those filters can modify each tree (e.g. removing a file or running
433 a perl rewrite on all files) or information about each commit.
434 Otherwise, all information (including original commit times or merge
435 information) will be preserved.
</p></div>
436 <div class=
"paragraph"><p>The command will only rewrite the
<em>positive
</em> refs mentioned in the
437 command line (e.g. if you pass
<em>a..b
</em>, only
<em>b
</em> will be rewritten).
438 If you specify no filters, the commits will be recommitted without any
439 changes, which would normally have no effect. Nevertheless, this may be
440 useful in the future for compensating for some git bugs or such,
441 therefore such a usage is permitted.
</p></div>
442 <div class=
"paragraph"><p><strong>NOTE
</strong>: This command honors
<tt>.git/info/grafts
</tt>. If you have any grafts
443 defined, running this command will make them permanent.
</p></div>
444 <div class=
"paragraph"><p><strong>WARNING
</strong>! The rewritten history will have different object names for all
445 the objects and will not converge with the original branch. You will not
446 be able to easily push and distribute the rewritten branch on top of the
447 original branch. Please do not use this command if you do not know the
448 full implications, and avoid using it anyway, if a simple single commit
449 would suffice to fix your problem. (See the
"RECOVERING FROM UPSTREAM
450 REBASE" section in
<a href=
"git-rebase.html">git-rebase(
1)
</a> for further information about
451 rewriting published history.)
</p></div>
452 <div class=
"paragraph"><p>Always verify that the rewritten version is correct: The original refs,
453 if different from the rewritten ones, will be stored in the namespace
454 <em>refs/original/
</em>.
</p></div>
455 <div class=
"paragraph"><p>Note that since this operation is very I/O expensive, it might
456 be a good idea to redirect the temporary directory off-disk with the
457 <em>-d
</em> option, e.g. on tmpfs. Reportedly the speedup is very noticeable.
</p></div>
458 <h3 id=
"_filters">Filters
</h3><div style=
"clear:left"></div>
459 <div class=
"paragraph"><p>The filters are applied in the order as listed below. The
<command
>
460 argument is always evaluated in the shell context using the
<em>eval
</em> command
461 (with the notable exception of the commit filter, for technical reasons).
462 Prior to that, the $GIT_COMMIT environment variable will be set to contain
463 the id of the commit being rewritten. Also, GIT_AUTHOR_NAME,
464 GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,
465 and GIT_COMMITTER_DATE are set according to the current commit. The values
466 of these variables after the filters have run, are used for the new commit.
467 If any evaluation of
<command
> returns a non-zero exit status, the whole
468 operation will be aborted.
</p></div>
469 <div class=
"paragraph"><p>A
<em>map
</em> function is available that takes an
"original sha1 id" argument
470 and outputs a
"rewritten sha1 id" if the commit has been already
471 rewritten, and
"original sha1 id" otherwise; the
<em>map
</em> function can
472 return several ids on separate lines if your commit filter emitted
473 multiple commits.
</p></div>
475 <h2 id=
"_options">OPTIONS
</h2>
476 <div class=
"sectionbody">
477 <div class=
"dlist"><dl>
479 --env-filter
<command
>
483 This filter may be used if you only need to modify the environment
484 in which the commit will be performed. Specifically, you might
485 want to rewrite the author/committer name/email/time environment
486 variables (see
<a href=
"git-commit-tree.html">git-commit-tree(
1)
</a> for details). Do not forget
487 to re-export the variables.
491 --tree-filter
<command
>
495 This is the filter for rewriting the tree and its contents.
496 The argument is evaluated in shell with the working
497 directory set to the root of the checked out tree. The new tree
498 is then used as-is (new files are auto-added, disappeared files
499 are auto-removed - neither .gitignore files nor any other ignore
500 rules
<strong>HAVE ANY EFFECT
</strong>!).
504 --index-filter
<command
>
508 This is the filter for rewriting the index. It is similar to the
509 tree filter but does not check out the tree, which makes it much
510 faster. Frequently used with
<tt>git rm --cached
511 --ignore-unmatch
…</tt>, see EXAMPLES below. For hairy
512 cases, see
<a href=
"git-update-index.html">git-update-index(
1)
</a>.
516 --parent-filter
<command
>
520 This is the filter for rewriting the commit
’s parent list.
521 It will receive the parent string on stdin and shall output
522 the new parent string on stdout. The parent string is in
523 the format described in
<a href=
"git-commit-tree.html">git-commit-tree(
1)
</a>: empty for
524 the initial commit,
"-p parent" for a normal commit and
525 "-p parent1 -p parent2 -p parent3 …" for a merge commit.
529 --msg-filter
<command
>
533 This is the filter for rewriting the commit messages.
534 The argument is evaluated in the shell with the original
535 commit message on standard input; its standard output is
536 used as the new commit message.
540 --commit-filter
<command
>
544 This is the filter for performing the commit.
545 If this filter is specified, it will be called instead of the
546 <em>git commit-tree
</em> command, with arguments of the form
547 "<TREE_ID> [(-p <PARENT_COMMIT_ID>)…]" and the log message on
548 stdin. The commit id is expected on stdout.
550 <div class=
"paragraph"><p>As a special extension, the commit filter may emit multiple
551 commit ids; in that case, the rewritten children of the original commit will
552 have all of them as parents.
</p></div>
553 <div class=
"paragraph"><p>You can use the
<em>map
</em> convenience function in this filter, and other
554 convenience functions, too. For example, calling
<em>skip_commit
"$@"</em>
555 will leave out the current commit (but not its changes! If you want
556 that, use
<em>git rebase
</em> instead).
</p></div>
557 <div class=
"paragraph"><p>You can also use the
<tt>git_commit_non_empty_tree
"$@"</tt> instead of
558 <tt>git commit-tree
"$@"</tt> if you don
’t wish to keep commits with a single parent
559 and that makes no change to the tree.
</p></div>
562 --tag-name-filter
<command
>
566 This is the filter for rewriting tag names. When passed,
567 it will be called for every tag ref that points to a rewritten
568 object (or to a tag object which points to a rewritten object).
569 The original tag name is passed via standard input, and the new
570 tag name is expected on standard output.
572 <div class=
"paragraph"><p>The original tags are not deleted, but can be overwritten;
573 use
"--tag-name-filter cat" to simply update the tags. In this
574 case, be very careful and make sure you have the old tags
575 backed up in case the conversion has run afoul.
</p></div>
576 <div class=
"paragraph"><p>Nearly proper rewriting of tag objects is supported. If the tag has
577 a message attached, a new tag object will be created with the same message,
578 author, and timestamp. If the tag has a signature attached, the
579 signature will be stripped. It is by definition impossible to preserve
580 signatures. The reason this is
"nearly" proper, is because ideally if
581 the tag did not change (points to the same object, has the same name, etc.)
582 it should retain any signature. That is not the case, signatures will always
583 be removed, buyer beware. There is also no support for changing the
584 author or timestamp (or the tag message for that matter). Tags which point
585 to other tags will be rewritten to point to the underlying commit.
</p></div>
588 --subdirectory-filter
<directory
>
592 Only look at the history which touches the given subdirectory.
593 The result will contain that directory (and only that) as its
594 project root. Implies
<a href=
"#Remap_to_ancestor">[Remap_to_ancestor]
</a>.
602 Some kind of filters will generate empty commits, that left the tree
603 untouched. This switch allow git-filter-branch to ignore such
604 commits. Though, this switch only applies for commits that have one
605 and only one parent, it will hence keep merges points. Also, this
606 option is not compatible with the use of
<em>--commit-filter
</em>. Though you
607 just need to use the function
<em>git_commit_non_empty_tree
"$@"</em> instead
608 of the
<tt>git commit-tree
"$@"</tt> idiom in your commit filter to make that
613 --original
<namespace
>
617 Use this option to set the namespace where the original commits
618 will be stored. The default value is
<em>refs/original
</em>.
626 Use this option to set the path to the temporary directory used for
627 rewriting. When applying a tree filter, the command needs to
628 temporarily check out the tree to some directory, which may consume
629 considerable space in case of large projects. By default it
630 does this in the
<em>.git-rewrite/
</em> directory but you can override
631 that choice by this parameter.
642 <em>git filter-branch
</em> refuses to start with an existing temporary
643 directory or when there are already refs starting with
644 <em>refs/original/
</em>, unless forced.
648 <rev-list options
>…
652 Arguments for
<em>git rev-list
</em>. All positive refs included by
653 these options are rewritten. You may also specify options
654 such as
<em>--all
</em>, but you must use
<em>--
</em> to separate them from
655 the
<em>git filter-branch
</em> options. Implies
<a href=
"#Remap_to_ancestor">[Remap_to_ancestor]
</a>.
659 <h3 id=
"Remap_to_ancestor">Remap to ancestor
</h3><div style=
"clear:left"></div>
660 <div class=
"paragraph"><p>By using
<a href=
"rev-list.html">rev-list(
1)
</a> arguments, e.g., path limiters, you can limit the
661 set of revisions which get rewritten. However, positive refs on the command
662 line are distinguished: we don
’t let them be excluded by such limiters. For
663 this purpose, they are instead rewritten to point at the nearest ancestor that
664 was not excluded.
</p></div>
666 <h2 id=
"_examples">Examples
</h2>
667 <div class=
"sectionbody">
668 <div class=
"paragraph"><p>Suppose you want to remove a file (containing confidential information
669 or copyright violation) from all commits:
</p></div>
670 <div class=
"listingblock">
671 <div class=
"content">
672 <pre><tt>git filter-branch --tree-filter 'rm filename' HEAD
</tt></pre>
674 <div class=
"paragraph"><p>However, if the file is absent from the tree of some commit,
675 a simple
<tt>rm filename
</tt> will fail for that tree and commit.
676 Thus you may instead want to use
<tt>rm -f filename
</tt> as the script.
</p></div>
677 <div class=
"paragraph"><p>Using
<tt>--index-filter
</tt> with
<em>git rm
</em> yields a significantly faster
678 version. Like with using
<tt>rm filename
</tt>,
<tt>git rm --cached filename
</tt>
679 will fail if the file is absent from the tree of a commit. If you
680 want to
"completely forget" a file, it does not matter when it entered
681 history, so we also add
<tt>--ignore-unmatch
</tt>:
</p></div>
682 <div class=
"listingblock">
683 <div class=
"content">
684 <pre><tt>git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD
</tt></pre>
686 <div class=
"paragraph"><p>Now, you will get the rewritten history saved in HEAD.
</p></div>
687 <div class=
"paragraph"><p>To rewrite the repository to look as if
<tt>foodir/
</tt> had been its project
688 root, and discard all other history:
</p></div>
689 <div class=
"listingblock">
690 <div class=
"content">
691 <pre><tt>git filter-branch --subdirectory-filter foodir -- --all
</tt></pre>
693 <div class=
"paragraph"><p>Thus you can, e.g., turn a library subdirectory into a repository of
694 its own. Note the
<tt>--
</tt> that separates
<em>filter-branch
</em> options from
695 revision options, and the
<tt>--all
</tt> to rewrite all branches and tags.
</p></div>
696 <div class=
"paragraph"><p>To set a commit (which typically is at the tip of another
697 history) to be the parent of the current initial commit, in
698 order to paste the other history behind the current history:
</p></div>
699 <div class=
"listingblock">
700 <div class=
"content">
701 <pre><tt>git filter-branch --parent-filter 'sed
"s/^\$/-p <graft-id>/"' HEAD
</tt></pre>
703 <div class=
"paragraph"><p>(if the parent string is empty - which happens when we are dealing with
704 the initial commit - add graftcommit as a parent). Note that this assumes
705 history with a single root (that is, no merge without common ancestors
706 happened). If this is not the case, use:
</p></div>
707 <div class=
"listingblock">
708 <div class=
"content">
709 <pre><tt>git filter-branch --parent-filter \
710 'test $GIT_COMMIT =
<commit-id
> && echo
"-p <graft-id>" || cat' HEAD
</tt></pre>
712 <div class=
"paragraph"><p>or even simpler:
</p></div>
713 <div class=
"listingblock">
714 <div class=
"content">
715 <pre><tt>echo
"$commit-id $graft-id" >> .git/info/grafts
716 git filter-branch $graft-id..HEAD
</tt></pre>
718 <div class=
"paragraph"><p>To remove commits authored by
"Darl McBribe" from the history:
</p></div>
719 <div class=
"listingblock">
720 <div class=
"content">
721 <pre><tt>git filter-branch --commit-filter '
722 if [
"$GIT_AUTHOR_NAME" =
"Darl McBribe" ];
726 git commit-tree
"$@";
729 <div class=
"paragraph"><p>The function
<em>skip_commit
</em> is defined as follows:
</p></div>
730 <div class=
"listingblock">
731 <div class=
"content">
732 <pre><tt>skip_commit()
743 <div class=
"paragraph"><p>The shift magic first throws away the tree id and then the -p
744 parameters. Note that this handles merges properly! In case Darl
745 committed a merge between P1 and P2, it will be propagated properly
746 and all children of the merge will become merge commits with P1,P2
747 as their parents instead of the merge commit.
</p></div>
748 <div class=
"paragraph"><p>You can rewrite the commit log messages using
<tt>--msg-filter
</tt>. For
749 example,
<em>git svn-id
</em> strings in a repository created by
<em>git svn
</em> can
750 be removed this way:
</p></div>
751 <div class=
"listingblock">
752 <div class=
"content">
753 <pre><tt>git filter-branch --msg-filter '
754 sed -e
"/^git-svn-id:/d"
757 <div class=
"paragraph"><p>To restrict rewriting to only part of the history, specify a revision
758 range in addition to the new branch name. The new branch name will
759 point to the top-most revision that a
<em>git rev-list
</em> of this range
760 will print.
</p></div>
761 <div class=
"paragraph"><p>If you need to add
<em>Acked-by
</em> lines to, say, the last
10 commits (none
762 of which is a merge), use this command:
</p></div>
763 <div class=
"listingblock">
764 <div class=
"content">
765 <pre><tt>git filter-branch --msg-filter '
767 echo
"Acked-by: Bugs Bunny <bunny@bugzilla.org>"
768 ' HEAD~
10..HEAD
</tt></pre>
770 <div class=
"paragraph"><p><strong>NOTE
</strong> the changes introduced by the commits, and which are not reverted
771 by subsequent commits, will still be in the rewritten branch. If you want
772 to throw out
<em>changes
</em> together with the commits, you should use the
773 interactive mode of
<em>git rebase
</em>.
</p></div>
774 <div class=
"paragraph"><p>Consider this history:
</p></div>
775 <div class=
"listingblock">
776 <div class=
"content">
777 <pre><tt> D--E--F--G--H
779 A--B-----C
</tt></pre>
781 <div class=
"paragraph"><p>To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:
</p></div>
782 <div class=
"listingblock">
783 <div class=
"content">
784 <pre><tt>git filter-branch ... C..H
</tt></pre>
786 <div class=
"paragraph"><p>To rewrite commits E,F,G,H, use one of these:
</p></div>
787 <div class=
"listingblock">
788 <div class=
"content">
789 <pre><tt>git filter-branch ... C..H --not D
790 git filter-branch ... D..H --not C
</tt></pre>
792 <div class=
"paragraph"><p>To move the whole tree into a subdirectory, or remove it from there:
</p></div>
793 <div class=
"listingblock">
794 <div class=
"content">
795 <pre><tt>git filter-branch --index-filter \
796 'git ls-files -s | sed
"s-\t\"*-
&newsubdir/-
" |
797 GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
798 git update-index --index-info &&
799 mv "$GIT_INDEX_FILE.new
" "$GIT_INDEX_FILE
"' HEAD</tt></pre>
802 <h2 id="_checklist_for_shrinking_a_repository
">Checklist for Shrinking a Repository</h2>
803 <div class="sectionbody
">
804 <div class="paragraph
"><p>git-filter-branch is often used to get rid of a subset of files,
805 usually with some combination of <tt>--index-filter</tt> and
806 <tt>--subdirectory-filter</tt>. People expect the resulting repository to
807 be smaller than the original, but you need a few more steps to
808 actually make it smaller, because git tries hard not to lose your
809 objects until you tell it to. First make sure that:</p></div>
810 <div class="ulist
"><ul>
813 You really removed all variants of a filename, if a blob was moved
814 over its lifetime. <tt>git log --name-only --follow --all --
815 filename</tt> can help you find renames.
820 You really filtered all refs: use <tt>--tag-name-filter cat --
821 --all</tt> when calling git-filter-branch.
825 <div class="paragraph
"><p>Then there are two ways to get a smaller repository. A safer way is
826 to clone, that keeps your original intact.</p></div>
827 <div class="ulist
"><ul>
830 Clone it with <tt>git clone file:///path/to/repo</tt>. The clone
831 will not have the removed objects. See <a href="git-clone.html
">git-clone(1)</a>. (Note
832 that cloning with a plain path just hardlinks everything!)
836 <div class="paragraph
"><p>If you really don’t want to clone it, for whatever reasons, check the
837 following points instead (in this order). This is a very destructive
838 approach, so <strong>make a backup</strong> or go back to cloning it. You have been
840 <div class="ulist
"><ul>
843 Remove the original refs backed up by git-filter-branch: say <tt>git
844 for-each-ref --format="%(refname)
" refs/original/ | xargs -n 1 git
850 Expire all reflogs with <tt>git reflog expire --expire=now --all</tt>.
855 Garbage collect all unreferenced objects with <tt>git gc --prune=now</tt>
856 (or if your git-gc is not new enough to support arguments to
857 <tt>--prune</tt>, use <tt>git repack -ad; git prune</tt> instead).
862 <h2 id="_git
">GIT</h2>
863 <div class="sectionbody
">
864 <div class="paragraph
"><p>Part of the <a href="git.html
">git(1)</a> suite</p></div>
867 <div id="footer-text
">
868 Last updated 2011-04-02 04:31:58 UTC