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.2.5" />
7 <style type=
"text/css">
9 p
, li
, dt
, dd
, div
, pre
, h1
, h2
, h3
, h4
, h5
, h6
{
11 border: 1px solid red;
16 margin: 1em 5% 1em 5%;
21 text-decoration: underline
;
39 h1
, h2
, h3
, h4
, h5
, h6
{
41 font-family: sans-serif
;
48 border-bottom: 2px solid silver
;
66 border: 1px solid silver
;
81 font-family: sans-serif
;
88 font-family: sans-serif
;
92 font-family: sans-serif
;
94 border-top: 2px solid silver
;
100 padding-bottom: 0.5em;
104 padding-bottom: 0.5em;
108 div
.tableblock
, div
.imageblock
, div
.exampleblock
, div
.verseblock
,
109 div
.quoteblock
, div
.literalblock
, div
.listingblock
, div
.sidebarblock
,
110 div
.admonitionblock
{
113 margin-bottom: 1.5em;
115 div
.admonitionblock
{
117 margin-bottom: 2.5em;
120 div
.content
{ /* Block element content. */
124 /* Block element titles. */
125 div
.title
, caption
.title
{
126 font-family: sans-serif
;
130 margin-bottom: 0.5em;
136 td div
.title:first-child
{
139 div
.content div
.title:first-child
{
142 div
.content
+ div
.title
{
146 div
.sidebarblock
> div
.content
{
148 border: 1px solid silver
;
155 div
.listingblock
> div
.content
{
156 border: 1px solid silver
;
161 div
.quoteblock
> div
.content
{
168 div
.verseblock
+ div
.attribution
{
172 div
.admonitionblock
.icon
{
176 text-decoration: underline
;
178 padding-right: 0.5em;
180 div
.admonitionblock td
.content
{
182 border-left: 2px solid silver
;
185 div
.exampleblock
> div
.content
{
186 border-left: 2px solid silver
;
190 div
.verseblock div
.content
{
194 div
.imageblock div
.content
{ padding-left: 0; }
195 div
.imageblock img
{ border: 1px solid silver
; }
196 span
.image img
{ border-style: none
; }
200 margin-bottom: 0.8em;
212 list-style-position: outside
;
215 list-style-type: lower-alpha
;
218 div
.tableblock
> table
{
219 border: 3px solid
#527bbd;
222 font-family: sans-serif
;
231 margin-bottom: 0.8em;
239 padding-right: 0.8em;
246 div#footer-badges
{ display: none
; }
251 font-family: sans-serif
;
255 margin-bottom: 0.1em;
258 div
.toclevel1
, div
.toclevel2
, div
.toclevel3
, div
.toclevel4
{
274 include1::./stylesheets
/xhtml11-manpage
.css
[]
275 /* Workarounds for IE6's broken and incomplete CSS2. */
277 div
.sidebar-content
{
279 border: 1px solid silver
;
282 div
.sidebar-title
, div
.image-title
{
283 font-family: sans-serif
;
286 margin-bottom: 0.5em;
289 div
.listingblock div
.content
{
290 border: 1px solid silver
;
295 div
.quoteblock-content
{
299 div
.exampleblock-content
{
300 border-left: 2px solid silver
;
304 /* IE6 sets dynamically generated links as visited. */
305 div#toc
a:visited
{ color: blue
; }
307 <title>git-filter-branch(
1)
</title>
312 git-filter-branch(
1) Manual Page
315 <div class=
"sectionbody">
316 <p>git-filter-branch -
322 <div class=
"sectionbody">
323 <div class=
"verseblock">
324 <div class=
"content"><em>git filter-branch
</em> [--env-filter
<command
>] [--tree-filter
<command
>]
325 [--index-filter
<command
>] [--parent-filter
<command
>]
326 [--msg-filter
<command
>] [--commit-filter
<command
>]
327 [--tag-name-filter
<command
>] [--subdirectory-filter
<directory
>]
329 [--original
<namespace
>] [-d
<directory
>] [-f | --force]
330 [--] [
<rev-list options
>…]
</div></div>
332 <h2 id=
"_description">DESCRIPTION
</h2>
333 <div class=
"sectionbody">
334 <div class=
"para"><p>Lets you rewrite git revision history by rewriting the branches mentioned
335 in the
<rev-list options
>, applying custom filters on each revision.
336 Those filters can modify each tree (e.g. removing a file or running
337 a perl rewrite on all files) or information about each commit.
338 Otherwise, all information (including original commit times or merge
339 information) will be preserved.
</p></div>
340 <div class=
"para"><p>The command will only rewrite the _positive_ refs mentioned in the
341 command line (e.g. if you pass
<em>a..b
</em>, only
<em>b
</em> will be rewritten).
342 If you specify no filters, the commits will be recommitted without any
343 changes, which would normally have no effect. Nevertheless, this may be
344 useful in the future for compensating for some git bugs or such,
345 therefore such a usage is permitted.
</p></div>
346 <div class=
"para"><p><strong>NOTE
</strong>: This command honors
<tt>.git/info/grafts
</tt>. If you have any grafts
347 defined, running this command will make them permanent.
</p></div>
348 <div class=
"para"><p><strong>WARNING
</strong>! The rewritten history will have different object names for all
349 the objects and will not converge with the original branch. You will not
350 be able to easily push and distribute the rewritten branch on top of the
351 original branch. Please do not use this command if you do not know the
352 full implications, and avoid using it anyway, if a simple single commit
353 would suffice to fix your problem. (See the
"RECOVERING FROM UPSTREAM
354 REBASE" section in
<a href=
"git-rebase.html">git-rebase(
1)
</a> for further information about
355 rewriting published history.)
</p></div>
356 <div class=
"para"><p>Always verify that the rewritten version is correct: The original refs,
357 if different from the rewritten ones, will be stored in the namespace
358 <em>refs/original/
</em>.
</p></div>
359 <div class=
"para"><p>Note that since this operation is very I/O expensive, it might
360 be a good idea to redirect the temporary directory off-disk with the
361 <em>-d
</em> option, e.g. on tmpfs. Reportedly the speedup is very noticeable.
</p></div>
362 <h3 id=
"_filters">Filters
</h3><div style=
"clear:left"></div>
363 <div class=
"para"><p>The filters are applied in the order as listed below. The
<command
>
364 argument is always evaluated in the shell context using the
<em>eval
</em> command
365 (with the notable exception of the commit filter, for technical reasons).
366 Prior to that, the $GIT_COMMIT environment variable will be set to contain
367 the id of the commit being rewritten. Also, GIT_AUTHOR_NAME,
368 GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,
369 and GIT_COMMITTER_DATE are set according to the current commit. The values
370 of these variables after the filters have run, are used for the new commit.
371 If any evaluation of
<command
> returns a non-zero exit status, the whole
372 operation will be aborted.
</p></div>
373 <div class=
"para"><p>A
<em>map
</em> function is available that takes an
"original sha1 id" argument
374 and outputs a
"rewritten sha1 id" if the commit has been already
375 rewritten, and
"original sha1 id" otherwise; the
<em>map
</em> function can
376 return several ids on separate lines if your commit filter emitted
377 multiple commits.
</p></div>
379 <h2 id=
"_options">OPTIONS
</h2>
380 <div class=
"sectionbody">
381 <div class=
"vlist"><dl>
383 --env-filter
<command
>
387 This filter may be used if you only need to modify the environment
388 in which the commit will be performed. Specifically, you might
389 want to rewrite the author/committer name/email/time environment
390 variables (see
<a href=
"git-commit.html">git-commit(
1)
</a> for details). Do not forget
391 to re-export the variables.
395 --tree-filter
<command
>
399 This is the filter for rewriting the tree and its contents.
400 The argument is evaluated in shell with the working
401 directory set to the root of the checked out tree. The new tree
402 is then used as-is (new files are auto-added, disappeared files
403 are auto-removed - neither .gitignore files nor any other ignore
404 rules
<strong>HAVE ANY EFFECT
</strong>!).
408 --index-filter
<command
>
412 This is the filter for rewriting the index. It is similar to the
413 tree filter but does not check out the tree, which makes it much
414 faster. Frequently used with
<tt>git rm --cached
415 --ignore-unmatch
…</tt>, see EXAMPLES below. For hairy
416 cases, see
<a href=
"git-update-index.html">git-update-index(
1)
</a>.
420 --parent-filter
<command
>
424 This is the filter for rewriting the commit's parent list.
425 It will receive the parent string on stdin and shall output
426 the new parent string on stdout. The parent string is in
427 the format described in
<a href=
"git-commit-tree.html">git-commit-tree(
1)
</a>: empty for
428 the initial commit,
"-p parent" for a normal commit and
429 "-p parent1 -p parent2 -p parent3 …" for a merge commit.
433 --msg-filter
<command
>
437 This is the filter for rewriting the commit messages.
438 The argument is evaluated in the shell with the original
439 commit message on standard input; its standard output is
440 used as the new commit message.
444 --commit-filter
<command
>
448 This is the filter for performing the commit.
449 If this filter is specified, it will be called instead of the
450 <em>git commit-tree
</em> command, with arguments of the form
451 "<TREE_ID> [-p <PARENT_COMMIT_ID>]…" and the log message on
452 stdin. The commit id is expected on stdout.
454 <div class=
"para"><p>As a special extension, the commit filter may emit multiple
455 commit ids; in that case, the rewritten children of the original commit will
456 have all of them as parents.
</p></div>
457 <div class=
"para"><p>You can use the
<em>map
</em> convenience function in this filter, and other
458 convenience functions, too. For example, calling
<em>skip_commit
"$@"</em>
459 will leave out the current commit (but not its changes! If you want
460 that, use
<em>git rebase
</em> instead).
</p></div>
461 <div class=
"para"><p>You can also use the
<tt>git_commit_non_empty_tree
"$@"</tt> instead of
462 <tt>git commit-tree
"$@"</tt> if you don't wish to keep commits with a single parent
463 and that makes no change to the tree.
</p></div>
466 --tag-name-filter
<command
>
470 This is the filter for rewriting tag names. When passed,
471 it will be called for every tag ref that points to a rewritten
472 object (or to a tag object which points to a rewritten object).
473 The original tag name is passed via standard input, and the new
474 tag name is expected on standard output.
476 <div class=
"para"><p>The original tags are not deleted, but can be overwritten;
477 use
"--tag-name-filter cat" to simply update the tags. In this
478 case, be very careful and make sure you have the old tags
479 backed up in case the conversion has run afoul.
</p></div>
480 <div class=
"para"><p>Nearly proper rewriting of tag objects is supported. If the tag has
481 a message attached, a new tag object will be created with the same message,
482 author, and timestamp. If the tag has a signature attached, the
483 signature will be stripped. It is by definition impossible to preserve
484 signatures. The reason this is
"nearly" proper, is because ideally if
485 the tag did not change (points to the same object, has the same name, etc.)
486 it should retain any signature. That is not the case, signatures will always
487 be removed, buyer beware. There is also no support for changing the
488 author or timestamp (or the tag message for that matter). Tags which point
489 to other tags will be rewritten to point to the underlying commit.
</p></div>
492 --subdirectory-filter
<directory
>
496 Only look at the history which touches the given subdirectory.
497 The result will contain that directory (and only that) as its
498 project root. Implies --remap-to-ancestor.
506 Rewrite refs to the nearest rewritten ancestor instead of
509 <div class=
"para"><p>Normally, positive refs on the command line are only changed if the
510 commit they point to was rewritten. However, you can limit the extent
511 of this rewriting by using
<a href=
"rev-list.html">rev-list(
1)
</a> arguments, e.g., path
512 limiters. Refs pointing to such excluded commits would then normally
513 be ignored. With this option, they are instead rewritten to point at
514 the nearest ancestor that was not excluded.
</p></div>
521 Some kind of filters will generate empty commits, that left the tree
522 untouched. This switch allow git-filter-branch to ignore such
523 commits. Though, this switch only applies for commits that have one
524 and only one parent, it will hence keep merges points. Also, this
525 option is not compatible with the use of
<em>--commit-filter
</em>. Though you
526 just need to use the function
<em>git_commit_non_empty_tree
"$@"</em> instead
527 of the
<tt>git commit-tree
"$@"</tt> idiom in your commit filter to make that
532 --original
<namespace
>
536 Use this option to set the namespace where the original commits
537 will be stored. The default value is
<em>refs/original
</em>.
545 Use this option to set the path to the temporary directory used for
546 rewriting. When applying a tree filter, the command needs to
547 temporarily check out the tree to some directory, which may consume
548 considerable space in case of large projects. By default it
549 does this in the
<em>.git-rewrite/
</em> directory but you can override
550 that choice by this parameter.
561 <em>git filter-branch
</em> refuses to start with an existing temporary
562 directory or when there are already refs starting with
563 <em>refs/original/
</em>, unless forced.
567 <rev-list options
>…
571 Arguments for
<em>git rev-list
</em>. All positive refs included by
572 these options are rewritten. You may also specify options
573 such as
<em>--all
</em>, but you must use
<em>--
</em> to separate them from
574 the
<em>git filter-branch
</em> options.
579 <h2 id=
"_examples">Examples
</h2>
580 <div class=
"sectionbody">
581 <div class=
"para"><p>Suppose you want to remove a file (containing confidential information
582 or copyright violation) from all commits:
</p></div>
583 <div class=
"listingblock">
584 <div class=
"content">
585 <pre><tt>git filter-branch --tree-filter 'rm filename' HEAD
</tt></pre>
587 <div class=
"para"><p>However, if the file is absent from the tree of some commit,
588 a simple
<tt>rm filename
</tt> will fail for that tree and commit.
589 Thus you may instead want to use
<tt>rm -f filename
</tt> as the script.
</p></div>
590 <div class=
"para"><p>Using
<tt>--index-filter
</tt> with
<em>git rm
</em> yields a significantly faster
591 version. Like with using
<tt>rm filename
</tt>,
<tt>git rm --cached filename
</tt>
592 will fail if the file is absent from the tree of a commit. If you
593 want to
"completely forget" a file, it does not matter when it entered
594 history, so we also add
<tt>--ignore-unmatch
</tt>:
</p></div>
595 <div class=
"listingblock">
596 <div class=
"content">
597 <pre><tt>git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD
</tt></pre>
599 <div class=
"para"><p>Now, you will get the rewritten history saved in HEAD.
</p></div>
600 <div class=
"para"><p>To rewrite the repository to look as if
<tt>foodir/
</tt> had been its project
601 root, and discard all other history:
</p></div>
602 <div class=
"listingblock">
603 <div class=
"content">
604 <pre><tt>git filter-branch --subdirectory-filter foodir -- --all
</tt></pre>
606 <div class=
"para"><p>Thus you can, e.g., turn a library subdirectory into a repository of
607 its own. Note the
<tt>--
</tt> that separates
<em>filter-branch
</em> options from
608 revision options, and the
<tt>--all
</tt> to rewrite all branches and tags.
</p></div>
609 <div class=
"para"><p>To set a commit (which typically is at the tip of another
610 history) to be the parent of the current initial commit, in
611 order to paste the other history behind the current history:
</p></div>
612 <div class=
"listingblock">
613 <div class=
"content">
614 <pre><tt>git filter-branch --parent-filter 'sed
"s/^\$/-p <graft-id>/"' HEAD
</tt></pre>
616 <div class=
"para"><p>(if the parent string is empty - which happens when we are dealing with
617 the initial commit - add graftcommit as a parent). Note that this assumes
618 history with a single root (that is, no merge without common ancestors
619 happened). If this is not the case, use:
</p></div>
620 <div class=
"listingblock">
621 <div class=
"content">
622 <pre><tt>git filter-branch --parent-filter \
623 'test $GIT_COMMIT =
<commit-id
> && echo
"-p <graft-id>" || cat' HEAD
</tt></pre>
625 <div class=
"para"><p>or even simpler:
</p></div>
626 <div class=
"listingblock">
627 <div class=
"content">
628 <pre><tt>echo
"$commit-id $graft-id" >> .git/info/grafts
629 git filter-branch $graft-id..HEAD
</tt></pre>
631 <div class=
"para"><p>To remove commits authored by
"Darl McBribe" from the history:
</p></div>
632 <div class=
"listingblock">
633 <div class=
"content">
634 <pre><tt>git filter-branch --commit-filter '
635 if [
"$GIT_AUTHOR_NAME" =
"Darl McBribe" ];
639 git commit-tree
"$@";
642 <div class=
"para"><p>The function
<em>skip_commit
</em> is defined as follows:
</p></div>
643 <div class=
"listingblock">
644 <div class=
"content">
645 <pre><tt>skip_commit()
656 <div class=
"para"><p>The shift magic first throws away the tree id and then the -p
657 parameters. Note that this handles merges properly! In case Darl
658 committed a merge between P1 and P2, it will be propagated properly
659 and all children of the merge will become merge commits with P1,P2
660 as their parents instead of the merge commit.
</p></div>
661 <div class=
"para"><p>You can rewrite the commit log messages using
<tt>--msg-filter
</tt>. For
662 example,
<em>git svn-id
</em> strings in a repository created by
<em>git svn
</em> can
663 be removed this way:
</p></div>
664 <div class=
"listingblock">
665 <div class=
"content">
666 <pre><tt>git filter-branch --msg-filter '
667 sed -e
"/^git-svn-id:/d"
670 <div class=
"para"><p>To restrict rewriting to only part of the history, specify a revision
671 range in addition to the new branch name. The new branch name will
672 point to the top-most revision that a
<em>git rev-list
</em> of this range
673 will print.
</p></div>
674 <div class=
"para"><p>If you need to add
<em>Acked-by
</em> lines to, say, the last
10 commits (none
675 of which is a merge), use this command:
</p></div>
676 <div class=
"listingblock">
677 <div class=
"content">
678 <pre><tt>git filter-branch --msg-filter '
680 echo
"Acked-by: Bugs Bunny <bunny@bugzilla.org>"
681 ' HEAD~
10..HEAD
</tt></pre>
683 <div class=
"para"><p><strong>NOTE
</strong> the changes introduced by the commits, and which are not reverted
684 by subsequent commits, will still be in the rewritten branch. If you want
685 to throw out _changes_ together with the commits, you should use the
686 interactive mode of
<em>git rebase
</em>.
</p></div>
687 <div class=
"para"><p>Consider this history:
</p></div>
688 <div class=
"listingblock">
689 <div class=
"content">
690 <pre><tt> D--E--F--G--H
692 A--B-----C
</tt></pre>
694 <div class=
"para"><p>To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:
</p></div>
695 <div class=
"listingblock">
696 <div class=
"content">
697 <pre><tt>git filter-branch ... C..H
</tt></pre>
699 <div class=
"para"><p>To rewrite commits E,F,G,H, use one of these:
</p></div>
700 <div class=
"listingblock">
701 <div class=
"content">
702 <pre><tt>git filter-branch ... C..H --not D
703 git filter-branch ... D..H --not C
</tt></pre>
705 <div class=
"para"><p>To move the whole tree into a subdirectory, or remove it from there:
</p></div>
706 <div class=
"listingblock">
707 <div class=
"content">
708 <pre><tt>git filter-branch --index-filter \
709 'git ls-files -s | sed
"s-\t\"*-
&newsubdir/-
" |
710 GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
711 git update-index --index-info &&
712 mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' HEAD</tt></pre>
715 <h2 id="_checklist_for_shrinking_a_repository
">Checklist for Shrinking a Repository</h2>
716 <div class="sectionbody
">
717 <div class="para
"><p>git-filter-branch is often used to get rid of a subset of files,
718 usually with some combination of <tt>--index-filter</tt> and
719 <tt>--subdirectory-filter</tt>. People expect the resulting repository to
720 be smaller than the original, but you need a few more steps to
721 actually make it smaller, because git tries hard not to lose your
722 objects until you tell it to. First make sure that:</p></div>
723 <div class="ilist
"><ul>
726 You really removed all variants of a filename, if a blob was moved
727 over its lifetime. <tt>git log --name-only --follow --all --
728 filename</tt> can help you find renames.
733 You really filtered all refs: use <tt>--tag-name-filter cat --
734 --all</tt> when calling git-filter-branch.
738 <div class="para
"><p>Then there are two ways to get a smaller repository. A safer way is
739 to clone, that keeps your original intact.</p></div>
740 <div class="ilist
"><ul>
743 Clone it with <tt>git clone file:///path/to/repo</tt>. The clone
744 will not have the removed objects. See <a href="git-clone.html
">git-clone(1)</a>. (Note
745 that cloning with a plain path just hardlinks everything!)
749 <div class="para
"><p>If you really don't want to clone it, for whatever reasons, check the
750 following points instead (in this order). This is a very destructive
751 approach, so <strong>make a backup</strong> or go back to cloning it. You have been
753 <div class="ilist
"><ul>
756 Remove the original refs backed up by git-filter-branch: say <tt>git
757 for-each-ref --format="%(refname)
" refs/original/ | xargs -n 1 git
763 Expire all reflogs with <tt>git reflog expire --expire=now --all</tt>.
768 Garbage collect all unreferenced objects with <tt>git gc --prune=now</tt>
769 (or if your git-gc is not new enough to support arguments to
770 <tt>--prune</tt>, use <tt>git repack -ad; git prune</tt> instead).
775 <h2 id="_author
">Author</h2>
776 <div class="sectionbody
">
777 <div class="para
"><p>Written by Petr "Pasky
" Baudis <pasky@suse.cz>,
778 and the git list <git@vger.kernel.org></p></div>
780 <h2 id="_documentation
">Documentation</h2>
781 <div class="sectionbody
">
782 <div class="para
"><p>Documentation by Petr Baudis and the git list.</p></div>
784 <h2 id="_git
">GIT</h2>
785 <div class="sectionbody
">
786 <div class="para
"><p>Part of the <a href="git.html
">git(1)</a> suite</p></div>
789 <div id="footer-text
">
790 Last updated 2010-04-24 02:55:55 UTC