| blob | 101067694892b95322c597cf27d7b70d0ed2ae21 |
4 <head>
8 /* Debug borders */
10 /*
11 border: 1px solid red;
12 */
13 }
15 body {
17 }
19 a {
22 }
25 }
27 em {
29 }
31 strong {
33 }
35 tt {
37 }
45 }
49 }
50 h2 {
52 }
53 h3 {
55 }
56 h3 + * {
58 }
63 }
65 hr {
67 }
69 p {
72 }
74 pre {
77 }
79 span#author {
84 }
85 span#email {
86 }
87 span#revision {
89 }
91 div#footer {
97 }
98 div#footer-text {
101 }
102 div#footer-badges {
105 }
107 div#preamble,
114 }
118 }
122 }
124 /* Block element titles. */
131 }
134 }
138 }
141 }
144 }
150 }
154 }
159 }
163 }
167 }
170 }
179 }
183 }
188 }
192 }
198 dl {
201 }
202 dt {
206 }
209 }
213 }
216 }
220 }
221 thead {
224 }
225 tfoot {
227 }
232 }
235 }
240 }
243 }
247 }
249 div#toctitle {
256 }
261 }
265 }
269 }
273 }
275 /* Workarounds for IE6's broken and incomplete CSS2. */
281 }
287 }
293 }
297 }
302 }
304 /* IE6 sets dynamically generated links as visited. */
306 </style>
308 </head>
309 <body>
311 <h1>
312 git-filter-branch(1) Manual Page
313 </h1>
316 <p>git-filter-branch -
317 Rewrite branches
318 </p>
319 </div>
320 </div>
324 <div class="content"><em>git filter-branch</em> [--env-filter <command>] [--tree-filter <command>]
328 [--prune-empty]
331 </div>
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>
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
355 rewriting published history.)</p></div>
357 if different from the rewritten ones, will be stored in the namespace
360 be a good idea to redirect the temporary directory off-disk with the
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.
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
376 return several ids on separate lines if your commit filter emitted
377 multiple commits.</p></div>
378 </div>
382 <dt>
384 </dt>
385 <dd>
386 <p>
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
391 to re-export the variables.
392 </p>
393 </dd>
394 <dt>
396 </dt>
397 <dd>
398 <p>
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
405 </p>
406 </dd>
407 <dt>
409 </dt>
410 <dd>
411 <p>
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
417 </p>
418 </dd>
419 <dt>
421 </dt>
422 <dd>
423 <p>
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
428 the initial commit, "-p parent" for a normal commit and
429 "-p parent1 -p parent2 -p parent3 …" for a merge commit.
430 </p>
431 </dd>
432 <dt>
434 </dt>
435 <dd>
436 <p>
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.
441 </p>
442 </dd>
443 <dt>
445 </dt>
446 <dd>
447 <p>
448 This is the filter for performing the commit.
449 If this filter is specified, it will be called instead of the
451 "<TREE_ID> [-p <PARENT_COMMIT_ID>]…" and the log message on
452 stdin. The commit id is expected on stdout.
453 </p>
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
459 will leave out the current commit (but not its changes! If you want
463 and that makes no change to the tree.</p></div>
464 </dd>
465 <dt>
467 </dt>
468 <dd>
469 <p>
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.
475 </p>
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>
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>
490 </dd>
491 <dt>
493 </dt>
494 <dd>
495 <p>
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.
499 </p>
500 </dd>
501 <dt>
502 --prune-empty
503 </dt>
504 <dd>
505 <p>
506 Some kind of filters will generate empty commits, that left the tree
507 untouched. This switch allow git-filter-branch to ignore such
508 commits. Though, this switch only applies for commits that have one
509 and only one parent, it will hence keep merges points. Also, this
513 happen.
514 </p>
515 </dd>
516 <dt>
518 </dt>
519 <dd>
520 <p>
521 Use this option to set the namespace where the original commits
523 </p>
524 </dd>
525 <dt>
527 </dt>
528 <dd>
529 <p>
530 Use this option to set the path to the temporary directory used for
531 rewriting. When applying a tree filter, the command needs to
532 temporarily check out the tree to some directory, which may consume
533 considerable space in case of large projects. By default it
535 that choice by this parameter.
536 </p>
537 </dd>
538 <dt>
539 -f
540 </dt>
541 <dt>
542 --force
543 </dt>
544 <dd>
545 <p>
547 directory or when there are already refs starting with
549 </p>
550 </dd>
551 <dt>
553 </dt>
554 <dd>
555 <p>
557 these options are rewritten. You may also specify options
560 </p>
561 </dd>
562 </dl></div>
563 </div>
567 or copyright violation) from all commits:</p></div>
571 </div></div>
575 <div class="para"><p>Using <tt>--index-filter</tt> with <em>git-rm</em> yields a significantly faster
577 will fail if the file is absent from the tree of a commit. If you
578 want to "completely forget" a file, it does not matter when it entered
582 <pre><tt>git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD</tt></pre>
583 </div></div>
585 <div class="para"><p>To rewrite the repository to look as if <tt>foodir/</tt> had been its project
586 root, and discard all other history:</p></div>
590 </div></div>
595 history) to be the parent of the current initial commit, in
596 order to paste the other history behind the current history:</p></div>
600 </div></div>
602 the initial commit - add graftcommit as a parent). Note that this assumes
603 history with a single root (that is, no merge without common ancestors
604 happened). If this is not the case, use:</p></div>
607 <pre><tt>git filter-branch --parent-filter \
608 'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD</tt></pre>
609 </div></div>
614 git filter-branch $graft-id..HEAD</tt></pre>
615 </div></div>
619 <pre><tt>git filter-branch --commit-filter '
621 then
622 skip_commit "$@";
623 else
624 git commit-tree "$@";
625 fi' HEAD</tt></pre>
626 </div></div>
630 <pre><tt>skip_commit()
631 {
632 shift;
633 while [ -n "$1" ];
634 do
635 shift;
636 map "$1";
637 shift;
638 done;
639 }</tt></pre>
640 </div></div>
642 parameters. Note that this handles merges properly! In case Darl
643 committed a merge between P1 and P2, it will be propagated properly
644 and all children of the merge will become merge commits with P1,P2
645 as their parents instead of the merge commit.</p></div>
648 be removed this way:</p></div>
651 <pre><tt>git filter-branch --msg-filter '
652 sed -e "/^git-svn-id:/d"
653 '</tt></pre>
654 </div></div>
656 range in addition to the new branch name. The new branch name will
658 will print.</p></div>
659 <div class="para"><p>If you need to add <em>Acked-by</em> lines to, say, the last 10 commits (none
660 of which is a merge), use this command:</p></div>
663 <pre><tt>git filter-branch --msg-filter '
664 cat &&
665 echo "Acked-by: Bugs Bunny <bunny@bugzilla.org>"
667 </div></div>
668 <div class="para"><p><strong>NOTE</strong> the changes introduced by the commits, and which are not reverted
669 by subsequent commits, will still be in the rewritten branch. If you want
670 to throw out _changes_ together with the commits, you should use the
675 <pre><tt> D--E--F--G--H
676 / /
677 A--B-----C</tt></pre>
678 </div></div>
679 <div class="para"><p>To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:</p></div>
683 </div></div>
687 <pre><tt>git filter-branch ... C..H --not D
688 git filter-branch ... D..H --not C</tt></pre>
689 </div></div>
690 <div class="para"><p>To move the whole tree into a subdirectory, or remove it from there:</p></div>
693 <pre><tt>git filter-branch --index-filter \
694 'git ls-files -s | sed "s-\t-&newsubdir/-" |
695 GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
696 git update-index --index-info &&
697 mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' HEAD</tt></pre>
698 </div></div>
699 </div>
705 be smaller than the original, but you need a few more steps to
706 actually make it smaller, because git tries hard not to lose your
707 objects until you tell it to. First make sure that:</p></div>
709 <li>
710 <p>
711 You really removed all variants of a filename, if a blob was moved
712 over its lifetime. <tt>git log --name-only --follow --all --
713 filename</tt> can help you find renames.
714 </p>
715 </li>
716 <li>
717 <p>
718 You really filtered all refs: use <tt>--tag-name-filter cat --
719 --all</tt> when calling git-filter-branch.
720 </p>
721 </li>
722 </ul></div>
724 to clone, that keeps your original intact.</p></div>
726 <li>
727 <p>
730 that cloning with a plain path just hardlinks everything!)
731 </p>
732 </li>
733 </ul></div>
735 following points instead (in this order). This is a very destructive
737 warned.</p></div>
739 <li>
740 <p>
741 Remove the original refs backed up by git-filter-branch: say <tt>git
743 update-ref -d</tt>.
744 </p>
745 </li>
746 <li>
747 <p>
749 </p>
750 </li>
751 <li>
752 <p>
754 (or if your git-gc is not new enough to support arguments to
756 </p>
757 </li>
758 </ul></div>
759 </div>
764 </div>
768 </div>
772 </div>
776 </div>
777 </div>
778 </body>
779 </html>