| blob | 61bc94a5c9a27d777a7523c450769b157426b6f5 |
4 <head>
9 /* Debug borders */
11 /*
12 border: 1px solid red;
13 */
14 }
16 body {
18 }
20 a {
23 }
26 }
28 em {
31 }
33 strong {
36 }
38 tt {
40 }
48 }
52 }
53 h2 {
55 }
56 h3 {
58 }
59 h3 + * {
61 }
66 }
68 hr {
70 }
72 p {
75 }
79 }
81 pre {
84 }
86 span#author {
91 }
92 span#email {
93 }
96 }
98 div#footer {
104 }
105 div#footer-text {
108 }
109 div#footer-badges {
112 }
114 div#preamble {
117 }
123 }
127 }
131 }
133 /* Block element titles. */
141 }
144 }
148 }
151 }
154 }
160 }
166 }
171 }
175 }
180 }
183 }
187 }
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
191 }
200 }
204 }
209 }
215 dl {
218 }
219 dt {
224 }
227 }
231 }
234 }
237 }
240 }
243 }
246 }
253 }
257 }
258 thead {
261 }
262 tfoot {
264 }
267 }
270 }
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
274 }
278 }
282 }
288 }
291 }
294 }
300 }
303 }
307 }
311 }
315 }
317 div#toctitle {
324 }
329 }
333 }
337 }
341 }
342 /* Overrides for manpage documents */
343 h1 {
348 }
349 h2 {
351 }
354 }
358 }
360 /* Workarounds for IE6's broken and incomplete CSS2. */
366 }
373 }
379 }
384 }
388 }
392 }
397 }
399 /* IE6 sets dynamically generated links as visited. */
401 </style>
402 </head>
403 <body>
405 <h1>
406 git-filter-branch(1) Manual Page
407 </h1>
410 <p>git-filter-branch -
411 Rewrite branches
412 </p>
413 </div>
414 </div>
418 <div class="verseblock-content"><em>git filter-branch</em> [--env-filter <command>] [--tree-filter <command>]
422 [--prune-empty]
426 </div></div>
427 </div>
430 <div class="paragraph"><p>Lets you rewrite git revision history by rewriting the branches mentioned
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
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
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
456 be a good idea to redirect the temporary directory off-disk with the
459 <div class="paragraph"><p>The filters are applied in the order as listed below. The <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.
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
472 return several ids on separate lines if your commit filter emitted
473 multiple commits.</p></div>
474 </div>
480 </dt>
481 <dd>
482 <p>
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.
488 </p>
489 </dd>
492 </dt>
493 <dd>
494 <p>
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
501 </p>
502 </dd>
505 </dt>
506 <dd>
507 <p>
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
513 </p>
514 </dd>
517 </dt>
518 <dd>
519 <p>
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
524 the initial commit, "-p parent" for a normal commit and
525 "-p parent1 -p parent2 -p parent3 …" for a merge commit.
526 </p>
527 </dd>
530 </dt>
531 <dd>
532 <p>
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.
537 </p>
538 </dd>
541 </dt>
542 <dd>
543 <p>
544 This is the filter for performing the commit.
545 If this filter is specified, it will be called instead of the
547 "<TREE_ID> [(-p <PARENT_COMMIT_ID>)…]" and the log message on
548 stdin. The commit id is expected on stdout.
549 </p>
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
555 will leave out the current commit (but not its changes! If you want
557 <div class="paragraph"><p>You can also use the <tt>git_commit_non_empty_tree "$@"</tt> instead of
559 and that makes no change to the tree.</p></div>
560 </dd>
563 </dt>
564 <dd>
565 <p>
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.
571 </p>
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>
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>
586 </dd>
589 </dt>
590 <dd>
591 <p>
592 Only look at the history which touches the given subdirectory.
593 The result will contain that directory (and only that) as its
595 </p>
596 </dd>
598 --prune-empty
599 </dt>
600 <dd>
601 <p>
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
609 happen.
610 </p>
611 </dd>
614 </dt>
615 <dd>
616 <p>
617 Use this option to set the namespace where the original commits
619 </p>
620 </dd>
623 </dt>
624 <dd>
625 <p>
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
631 that choice by this parameter.
632 </p>
633 </dd>
635 -f
636 </dt>
638 --force
639 </dt>
640 <dd>
641 <p>
643 directory or when there are already refs starting with
645 </p>
646 </dd>
649 </dt>
650 <dd>
651 <p>
653 these options are rewritten. You may also specify options
655 the <em>git filter-branch</em> options. Implies <a href="#Remap_to_ancestor">[Remap_to_ancestor]</a>.
656 </p>
657 </dd>
658 </dl></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>
665 </div>
668 <div class="paragraph"><p>Suppose you want to remove a file (containing confidential information
669 or copyright violation) from all commits:</p></div>
673 </div></div>
677 <div class="paragraph"><p>Using <tt>--index-filter</tt> with <em>git rm</em> yields a significantly faster
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
684 <pre><tt>git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD</tt></pre>
685 </div></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>
692 </div></div>
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>
702 </div></div>
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>
709 <pre><tt>git filter-branch --parent-filter \
710 'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD</tt></pre>
711 </div></div>
716 git filter-branch $graft-id..HEAD</tt></pre>
717 </div></div>
718 <div class="paragraph"><p>To remove commits authored by "Darl McBribe" from the history:</p></div>
721 <pre><tt>git filter-branch --commit-filter '
723 then
724 skip_commit "$@";
725 else
726 git commit-tree "$@";
727 fi' HEAD</tt></pre>
728 </div></div>
732 <pre><tt>skip_commit()
733 {
734 shift;
735 while [ -n "$1" ];
736 do
737 shift;
738 map "$1";
739 shift;
740 done;
741 }</tt></pre>
742 </div></div>
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
750 be removed this way:</p></div>
753 <pre><tt>git filter-branch --msg-filter '
754 sed -e "/^git-svn-id:/d"
755 '</tt></pre>
756 </div></div>
758 range in addition to the new branch name. The new branch name will
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>
765 <pre><tt>git filter-branch --msg-filter '
766 cat &&
767 echo "Acked-by: Bugs Bunny <bunny@bugzilla.org>"
769 </div></div>
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
777 <pre><tt> D--E--F--G--H
778 / /
779 A--B-----C</tt></pre>
780 </div></div>
781 <div class="paragraph"><p>To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:</p></div>
785 </div></div>
789 <pre><tt>git filter-branch ... C..H --not D
790 git filter-branch ... D..H --not C</tt></pre>
791 </div></div>
792 <div class="paragraph"><p>To move the whole tree into a subdirectory, or remove it from there:</p></div>
795 <pre><tt>git filter-branch --index-filter \
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>
800 </div></div>
801 </div>
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>
811 <li>
812 <p>
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.
816 </p>
817 </li>
818 <li>
819 <p>
820 You really filtered all refs: use <tt>--tag-name-filter cat --
821 --all</tt> when calling git-filter-branch.
822 </p>
823 </li>
824 </ul></div>
826 to clone, that keeps your original intact.</p></div>
828 <li>
829 <p>
830 Clone it with <tt>git clone file:///path/to/repo</tt>. The clone
832 that cloning with a plain path just hardlinks everything!)
833 </p>
834 </li>
835 </ul></div>
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
839 warned.</p></div>
841 <li>
842 <p>
843 Remove the original refs backed up by git-filter-branch: say <tt>git
845 update-ref -d</tt>.
846 </p>
847 </li>
848 <li>
849 <p>
850 Expire all reflogs with <tt>git reflog expire --expire=now --all</tt>.
851 </p>
852 </li>
853 <li>
854 <p>
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).
858 </p>
859 </li>
860 </ul></div>
861 </div>
864 <div class="paragraph"><p>Written by Petr "Pasky" Baudis <<a href="mailto:pasky@suse.cz">pasky@suse.cz</a>>,
866 </div>
870 </div>
874 </div>
877 Last updated 2010-11-06 00:41:57 UTC
878 </div>
879 </div>
880 </body>
881 </html>