1GIT-FILTER-BRANCH(1)              Git Manual              GIT-FILTER-BRANCH(1)
2
3
4

NAME

6       git-filter-branch - Rewrite branches
7

SYNOPSIS

9       git filter-branch [--setup <command>] [--subdirectory-filter <directory>]
10               [--env-filter <command>] [--tree-filter <command>]
11               [--index-filter <command>] [--parent-filter <command>]
12               [--msg-filter <command>] [--commit-filter <command>]
13               [--tag-name-filter <command>] [--prune-empty]
14               [--original <namespace>] [-d <directory>] [-f | --force]
15               [--state-branch <branch>] [--] [<rev-list options>...]
16

WARNING

18       git filter-branch has a plethora of pitfalls that can produce
19       non-obvious manglings of the intended history rewrite (and can leave
20       you with little time to investigate such problems since it has such
21       abysmal performance). These safety and performance issues cannot be
22       backward compatibly fixed and as such, its use is not recommended.
23       Please use an alternative history filtering tool such as git
24       filter-repo[1]. If you still need to use git filter-branch, please
25       carefully read the section called “SAFETY” (and the section called
26       “PERFORMANCE”) to learn about the land mines of filter-branch, and then
27       vigilantly avoid as many of the hazards listed there as reasonably
28       possible.
29

DESCRIPTION

31       Lets you rewrite Git revision history by rewriting the branches
32       mentioned in the <rev-list options>, applying custom filters on each
33       revision. Those filters can modify each tree (e.g. removing a file or
34       running a perl rewrite on all files) or information about each commit.
35       Otherwise, all information (including original commit times or merge
36       information) will be preserved.
37
38       The command will only rewrite the positive refs mentioned in the
39       command line (e.g. if you pass a..b, only b will be rewritten). If you
40       specify no filters, the commits will be recommitted without any
41       changes, which would normally have no effect. Nevertheless, this may be
42       useful in the future for compensating for some Git bugs or such,
43       therefore such a usage is permitted.
44
45       NOTE: This command honors .git/info/grafts file and refs in the
46       refs/replace/ namespace. If you have any grafts or replacement refs
47       defined, running this command will make them permanent.
48
49       WARNING! The rewritten history will have different object names for all
50       the objects and will not converge with the original branch. You will
51       not be able to easily push and distribute the rewritten branch on top
52       of the original branch. Please do not use this command if you do not
53       know the full implications, and avoid using it anyway, if a simple
54       single commit would suffice to fix your problem. (See the "RECOVERING
55       FROM UPSTREAM REBASE" section in git-rebase(1) for further information
56       about rewriting published history.)
57
58       Always verify that the rewritten version is correct: The original refs,
59       if different from the rewritten ones, will be stored in the namespace
60       refs/original/.
61
62       Note that since this operation is very I/O expensive, it might be a
63       good idea to redirect the temporary directory off-disk with the -d
64       option, e.g. on tmpfs. Reportedly the speedup is very noticeable.
65
66   Filters
67       The filters are applied in the order as listed below. The <command>
68       argument is always evaluated in the shell context using the eval
69       command (with the notable exception of the commit filter, for technical
70       reasons). Prior to that, the $GIT_COMMIT environment variable will be
71       set to contain the id of the commit being rewritten. Also,
72       GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME,
73       GIT_COMMITTER_EMAIL, and GIT_COMMITTER_DATE are taken from the current
74       commit and exported to the environment, in order to affect the author
75       and committer identities of the replacement commit created by git-
76       commit-tree(1) after the filters have run.
77
78       If any evaluation of <command> returns a non-zero exit status, the
79       whole operation will be aborted.
80
81       A map function is available that takes an "original sha1 id" argument
82       and outputs a "rewritten sha1 id" if the commit has been already
83       rewritten, and "original sha1 id" otherwise; the map function can
84       return several ids on separate lines if your commit filter emitted
85       multiple commits.
86

OPTIONS

88       --setup <command>
89           This is not a real filter executed for each commit but a one time
90           setup just before the loop. Therefore no commit-specific variables
91           are defined yet. Functions or variables defined here can be used or
92           modified in the following filter steps except the commit filter,
93           for technical reasons.
94
95       --subdirectory-filter <directory>
96           Only look at the history which touches the given subdirectory. The
97           result will contain that directory (and only that) as its project
98           root. Implies the section called “Remap to ancestor”.
99
100       --env-filter <command>
101           This filter may be used if you only need to modify the environment
102           in which the commit will be performed. Specifically, you might want
103           to rewrite the author/committer name/email/time environment
104           variables (see git-commit-tree(1) for details).
105
106       --tree-filter <command>
107           This is the filter for rewriting the tree and its contents. The
108           argument is evaluated in shell with the working directory set to
109           the root of the checked out tree. The new tree is then used as-is
110           (new files are auto-added, disappeared files are auto-removed -
111           neither .gitignore files nor any other ignore rules HAVE ANY
112           EFFECT!).
113
114       --index-filter <command>
115           This is the filter for rewriting the index. It is similar to the
116           tree filter but does not check out the tree, which makes it much
117           faster. Frequently used with git rm --cached --ignore-unmatch ...,
118           see EXAMPLES below. For hairy cases, see git-update-index(1).
119
120       --parent-filter <command>
121           This is the filter for rewriting the commit’s parent list. It will
122           receive the parent string on stdin and shall output the new parent
123           string on stdout. The parent string is in the format described in
124           git-commit-tree(1): empty for the initial commit, "-p parent" for a
125           normal commit and "-p parent1 -p parent2 -p parent3 ..." for a
126           merge commit.
127
128       --msg-filter <command>
129           This is the filter for rewriting the commit messages. The argument
130           is evaluated in the shell with the original commit message on
131           standard input; its standard output is used as the new commit
132           message.
133
134       --commit-filter <command>
135           This is the filter for performing the commit. If this filter is
136           specified, it will be called instead of the git commit-tree
137           command, with arguments of the form "<TREE_ID> [(-p
138           <PARENT_COMMIT_ID>)...]" and the log message on stdin. The commit
139           id is expected on stdout.
140
141           As a special extension, the commit filter may emit multiple commit
142           ids; in that case, the rewritten children of the original commit
143           will have all of them as parents.
144
145           You can use the map convenience function in this filter, and other
146           convenience functions, too. For example, calling skip_commit "$@"
147           will leave out the current commit (but not its changes! If you want
148           that, use git rebase instead).
149
150           You can also use the git_commit_non_empty_tree "$@" instead of git
151           commit-tree "$@" if you don’t wish to keep commits with a single
152           parent and that makes no change to the tree.
153
154       --tag-name-filter <command>
155           This is the filter for rewriting tag names. When passed, it will be
156           called for every tag ref that points to a rewritten object (or to a
157           tag object which points to a rewritten object). The original tag
158           name is passed via standard input, and the new tag name is expected
159           on standard output.
160
161           The original tags are not deleted, but can be overwritten; use
162           "--tag-name-filter cat" to simply update the tags. In this case, be
163           very careful and make sure you have the old tags backed up in case
164           the conversion has run afoul.
165
166           Nearly proper rewriting of tag objects is supported. If the tag has
167           a message attached, a new tag object will be created with the same
168           message, author, and timestamp. If the tag has a signature
169           attached, the signature will be stripped. It is by definition
170           impossible to preserve signatures. The reason this is "nearly"
171           proper, is because ideally if the tag did not change (points to the
172           same object, has the same name, etc.) it should retain any
173           signature. That is not the case, signatures will always be removed,
174           buyer beware. There is also no support for changing the author or
175           timestamp (or the tag message for that matter). Tags which point to
176           other tags will be rewritten to point to the underlying commit.
177
178       --prune-empty
179           Some filters will generate empty commits that leave the tree
180           untouched. This option instructs git-filter-branch to remove such
181           commits if they have exactly one or zero non-pruned parents; merge
182           commits will therefore remain intact. This option cannot be used
183           together with --commit-filter, though the same effect can be
184           achieved by using the provided git_commit_non_empty_tree function
185           in a commit filter.
186
187       --original <namespace>
188           Use this option to set the namespace where the original commits
189           will be stored. The default value is refs/original.
190
191       -d <directory>
192           Use this option to set the path to the temporary directory used for
193           rewriting. When applying a tree filter, the command needs to
194           temporarily check out the tree to some directory, which may consume
195           considerable space in case of large projects. By default it does
196           this in the .git-rewrite/ directory but you can override that
197           choice by this parameter.
198
199       -f, --force
200           git filter-branch refuses to start with an existing temporary
201           directory or when there are already refs starting with
202           refs/original/, unless forced.
203
204       --state-branch <branch>
205           This option will cause the mapping from old to new objects to be
206           loaded from named branch upon startup and saved as a new commit to
207           that branch upon exit, enabling incremental of large trees. If
208           <branch> does not exist it will be created.
209
210       <rev-list options>...
211           Arguments for git rev-list. All positive refs included by these
212           options are rewritten. You may also specify options such as --all,
213           but you must use -- to separate them from the git filter-branch
214           options. Implies the section called “Remap to ancestor”.
215
216   Remap to ancestor
217       By using git-rev-list(1) arguments, e.g., path limiters, you can limit
218       the set of revisions which get rewritten. However, positive refs on the
219       command line are distinguished: we don’t let them be excluded by such
220       limiters. For this purpose, they are instead rewritten to point at the
221       nearest ancestor that was not excluded.
222

EXIT STATUS

224       On success, the exit status is 0. If the filter can’t find any commits
225       to rewrite, the exit status is 2. On any other error, the exit status
226       may be any other non-zero value.
227

EXAMPLES

229       Suppose you want to remove a file (containing confidential information
230       or copyright violation) from all commits:
231
232           git filter-branch --tree-filter 'rm filename' HEAD
233
234       However, if the file is absent from the tree of some commit, a simple
235       rm filename will fail for that tree and commit. Thus you may instead
236       want to use rm -f filename as the script.
237
238       Using --index-filter with git rm yields a significantly faster version.
239       Like with using rm filename, git rm --cached filename will fail if the
240       file is absent from the tree of a commit. If you want to "completely
241       forget" a file, it does not matter when it entered history, so we also
242       add --ignore-unmatch:
243
244           git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD
245
246       Now, you will get the rewritten history saved in HEAD.
247
248       To rewrite the repository to look as if foodir/ had been its project
249       root, and discard all other history:
250
251           git filter-branch --subdirectory-filter foodir -- --all
252
253       Thus you can, e.g., turn a library subdirectory into a repository of
254       its own. Note the -- that separates filter-branch options from revision
255       options, and the --all to rewrite all branches and tags.
256
257       To set a commit (which typically is at the tip of another history) to
258       be the parent of the current initial commit, in order to paste the
259       other history behind the current history:
260
261           git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
262
263       (if the parent string is empty - which happens when we are dealing with
264       the initial commit - add graftcommit as a parent). Note that this
265       assumes history with a single root (that is, no merge without common
266       ancestors happened). If this is not the case, use:
267
268           git filter-branch --parent-filter \
269                   'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD
270
271       or even simpler:
272
273           git replace --graft $commit-id $graft-id
274           git filter-branch $graft-id..HEAD
275
276       To remove commits authored by "Darl McBribe" from the history:
277
278           git filter-branch --commit-filter '
279                   if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
280                   then
281                           skip_commit "$@";
282                   else
283                           git commit-tree "$@";
284                   fi' HEAD
285
286       The function skip_commit is defined as follows:
287
288           skip_commit()
289           {
290                   shift;
291                   while [ -n "$1" ];
292                   do
293                           shift;
294                           map "$1";
295                           shift;
296                   done;
297           }
298
299       The shift magic first throws away the tree id and then the -p
300       parameters. Note that this handles merges properly! In case Darl
301       committed a merge between P1 and P2, it will be propagated properly and
302       all children of the merge will become merge commits with P1,P2 as their
303       parents instead of the merge commit.
304
305       NOTE the changes introduced by the commits, and which are not reverted
306       by subsequent commits, will still be in the rewritten branch. If you
307       want to throw out changes together with the commits, you should use the
308       interactive mode of git rebase.
309
310       You can rewrite the commit log messages using --msg-filter. For
311       example, git svn-id strings in a repository created by git svn can be
312       removed this way:
313
314           git filter-branch --msg-filter '
315                   sed -e "/^git-svn-id:/d"
316           '
317
318       If you need to add Acked-by lines to, say, the last 10 commits (none of
319       which is a merge), use this command:
320
321           git filter-branch --msg-filter '
322                   cat &&
323                   echo "Acked-by: Bugs Bunny <bunny@bugzilla.org>"
324           ' HEAD~10..HEAD
325
326       The --env-filter option can be used to modify committer and/or author
327       identity. For example, if you found out that your commits have the
328       wrong identity due to a misconfigured user.email, you can make a
329       correction, before publishing the project, like this:
330
331           git filter-branch --env-filter '
332                   if test "$GIT_AUTHOR_EMAIL" = "root@localhost"
333                   then
334                           GIT_AUTHOR_EMAIL=john@example.com
335                   fi
336                   if test "$GIT_COMMITTER_EMAIL" = "root@localhost"
337                   then
338                           GIT_COMMITTER_EMAIL=john@example.com
339                   fi
340           ' -- --all
341
342       To restrict rewriting to only part of the history, specify a revision
343       range in addition to the new branch name. The new branch name will
344       point to the top-most revision that a git rev-list of this range will
345       print.
346
347       Consider this history:
348
349                D--E--F--G--H
350               /     /
351           A--B-----C
352
353       To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:
354
355           git filter-branch ... C..H
356
357       To rewrite commits E,F,G,H, use one of these:
358
359           git filter-branch ... C..H --not D
360           git filter-branch ... D..H --not C
361
362       To move the whole tree into a subdirectory, or remove it from there:
363
364           git filter-branch --index-filter \
365                   'git ls-files -s | sed "s-\t\"*-&newsubdir/-" |
366                           GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
367                                   git update-index --index-info &&
368                    mv "$GIT_INDEX_FILE.new" "$GIT_INDEX_FILE"' HEAD
369

CHECKLIST FOR SHRINKING A REPOSITORY

371       git-filter-branch can be used to get rid of a subset of files, usually
372       with some combination of --index-filter and --subdirectory-filter.
373       People expect the resulting repository to be smaller than the original,
374       but you need a few more steps to actually make it smaller, because Git
375       tries hard not to lose your objects until you tell it to. First make
376       sure that:
377
378       •   You really removed all variants of a filename, if a blob was moved
379           over its lifetime.  git log --name-only --follow --all -- filename
380           can help you find renames.
381
382       •   You really filtered all refs: use --tag-name-filter cat -- --all
383           when calling git-filter-branch.
384
385       Then there are two ways to get a smaller repository. A safer way is to
386       clone, that keeps your original intact.
387
388       •   Clone it with git clone file:///path/to/repo. The clone will not
389           have the removed objects. See git-clone(1). (Note that cloning with
390           a plain path just hardlinks everything!)
391
392       If you really don’t want to clone it, for whatever reasons, check the
393       following points instead (in this order). This is a very destructive
394       approach, so make a backup or go back to cloning it. You have been
395       warned.
396
397       •   Remove the original refs backed up by git-filter-branch: say git
398           for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git
399           update-ref -d.
400
401       •   Expire all reflogs with git reflog expire --expire=now --all.
402
403       •   Garbage collect all unreferenced objects with git gc --prune=now
404           (or if your git-gc is not new enough to support arguments to
405           --prune, use git repack -ad; git prune instead).
406

PERFORMANCE

408       The performance of git-filter-branch is glacially slow; its design
409       makes it impossible for a backward-compatible implementation to ever be
410       fast:
411
412       •   In editing files, git-filter-branch by design checks out each and
413           every commit as it existed in the original repo. If your repo has
414           10^5 files and 10^5 commits, but each commit only modifies five
415           files, then git-filter-branch will make you do 10^10 modifications,
416           despite only having (at most) 5*10^5 unique blobs.
417
418       •   If you try and cheat and try to make git-filter-branch only work on
419           files modified in a commit, then two things happen
420
421           •   you run into problems with deletions whenever the user is
422               simply trying to rename files (because attempting to delete
423               files that don’t exist looks like a no-op; it takes some
424               chicanery to remap deletes across file renames when the renames
425               happen via arbitrary user-provided shell)
426
427           •   even if you succeed at the map-deletes-for-renames chicanery,
428               you still technically violate backward compatibility because
429               users are allowed to filter files in ways that depend upon
430               topology of commits instead of filtering solely based on file
431               contents or names (though this has not been observed in the
432               wild).
433
434       •   Even if you don’t need to edit files but only want to e.g. rename
435           or remove some and thus can avoid checking out each file (i.e. you
436           can use --index-filter), you still are passing shell snippets for
437           your filters. This means that for every commit, you have to have a
438           prepared git repo where those filters can be run. That’s a
439           significant setup.
440
441       •   Further, several additional files are created or updated per commit
442           by git-filter-branch. Some of these are for supporting the
443           convenience functions provided by git-filter-branch (such as
444           map()), while others are for keeping track of internal state (but
445           could have also been accessed by user filters; one of
446           git-filter-branch’s regression tests does so). This essentially
447           amounts to using the filesystem as an IPC mechanism between
448           git-filter-branch and the user-provided filters. Disks tend to be a
449           slow IPC mechanism, and writing these files also effectively
450           represents a forced synchronization point between separate
451           processes that we hit with every commit.
452
453       •   The user-provided shell commands will likely involve a pipeline of
454           commands, resulting in the creation of many processes per commit.
455           Creating and running another process takes a widely varying amount
456           of time between operating systems, but on any platform it is very
457           slow relative to invoking a function.
458
459       •   git-filter-branch itself is written in shell, which is kind of
460           slow. This is the one performance issue that could be
461           backward-compatibly fixed, but compared to the above problems that
462           are intrinsic to the design of git-filter-branch, the language of
463           the tool itself is a relatively minor issue.
464
465           •   Side note: Unfortunately, people tend to fixate on the
466               written-in-shell aspect and periodically ask if
467               git-filter-branch could be rewritten in another language to fix
468               the performance issues. Not only does that ignore the bigger
469               intrinsic problems with the design, it’d help less than you’d
470               expect: if git-filter-branch itself were not shell, then the
471               convenience functions (map(), skip_commit(), etc) and the
472               --setup argument could no longer be executed once at the
473               beginning of the program but would instead need to be prepended
474               to every user filter (and thus re-executed with every commit).
475
476       The git filter-repo[1] tool is an alternative to git-filter-branch
477       which does not suffer from these performance problems or the safety
478       problems (mentioned below). For those with existing tooling which
479       relies upon git-filter-branch, git filter-repo also provides
480       filter-lamely[2], a drop-in git-filter-branch replacement (with a few
481       caveats). While filter-lamely suffers from all the same safety issues
482       as git-filter-branch, it at least ameliorates the performance issues a
483       little.
484

SAFETY

486       git-filter-branch is riddled with gotchas resulting in various ways to
487       easily corrupt repos or end up with a mess worse than what you started
488       with:
489
490       •   Someone can have a set of "working and tested filters" which they
491           document or provide to a coworker, who then runs them on a
492           different OS where the same commands are not working/tested (some
493           examples in the git-filter-branch manpage are also affected by
494           this). BSD vs. GNU userland differences can really bite. If lucky,
495           error messages are spewed. But just as likely, the commands either
496           don’t do the filtering requested, or silently corrupt by making
497           some unwanted change. The unwanted change may only affect a few
498           commits, so it’s not necessarily obvious either. (The fact that
499           problems won’t necessarily be obvious means they are likely to go
500           unnoticed until the rewritten history is in use for quite a while,
501           at which point it’s really hard to justify another flag-day for
502           another rewrite.)
503
504       •   Filenames with spaces are often mishandled by shell snippets since
505           they cause problems for shell pipelines. Not everyone is familiar
506           with find -print0, xargs -0, git-ls-files -z, etc. Even people who
507           are familiar with these may assume such flags are not relevant
508           because someone else renamed any such files in their repo back
509           before the person doing the filtering joined the project. And
510           often, even those familiar with handling arguments with spaces may
511           not do so just because they aren’t in the mindset of thinking about
512           everything that could possibly go wrong.
513
514       •   Non-ascii filenames can be silently removed despite being in a
515           desired directory. Keeping only wanted paths is often done using
516           pipelines like git ls-files | grep -v ^WANTED_DIR/ | xargs git rm.
517           ls-files will only quote filenames if needed, so folks may not
518           notice that one of the files didn’t match the regex (at least not
519           until it’s much too late). Yes, someone who knows about
520           core.quotePath can avoid this (unless they have other special
521           characters like \t, \n, or "), and people who use ls-files -z with
522           something other than grep can avoid this, but that doesn’t mean
523           they will.
524
525       •   Similarly, when moving files around, one can find that filenames
526           with non-ascii or special characters end up in a different
527           directory, one that includes a double quote character. (This is
528           technically the same issue as above with quoting, but perhaps an
529           interesting different way that it can and has manifested as a
530           problem.)
531
532       •   It’s far too easy to accidentally mix up old and new history. It’s
533           still possible with any tool, but git-filter-branch almost invites
534           it. If lucky, the only downside is users getting frustrated that
535           they don’t know how to shrink their repo and remove the old stuff.
536           If unlucky, they merge old and new history and end up with multiple
537           "copies" of each commit, some of which have unwanted or sensitive
538           files and others which don’t. This comes about in multiple
539           different ways:
540
541           •   the default to only doing a partial history rewrite (--all is
542               not the default and few examples show it)
543
544           •   the fact that there’s no automatic post-run cleanup
545
546           •   the fact that --tag-name-filter (when used to rename tags)
547               doesn’t remove the old tags but just adds new ones with the new
548               name
549
550           •   the fact that little educational information is provided to
551               inform users of the ramifications of a rewrite and how to avoid
552               mixing old and new history. For example, this man page
553               discusses how users need to understand that they need to rebase
554               their changes for all their branches on top of new history (or
555               delete and reclone), but that’s only one of multiple concerns
556               to consider. See the "DISCUSSION" section of the git
557               filter-repo manual page for more details.
558
559       •   Annotated tags can be accidentally converted to lightweight tags,
560           due to either of two issues:
561
562           •   Someone can do a history rewrite, realize they messed up,
563               restore from the backups in refs/original/, and then redo their
564               git-filter-branch command. (The backup in refs/original/ is not
565               a real backup; it dereferences tags first.)
566
567           •   Running git-filter-branch with either --tags or --all in your
568               <rev-list options>. In order to retain annotated tags as
569               annotated, you must use --tag-name-filter (and must not have
570               restored from refs/original/ in a previously botched rewrite).
571
572       •   Any commit messages that specify an encoding will become corrupted
573           by the rewrite; git-filter-branch ignores the encoding, takes the
574           original bytes, and feeds it to commit-tree without telling it the
575           proper encoding. (This happens whether or not --msg-filter is
576           used.)
577
578       •   Commit messages (even if they are all UTF-8) by default become
579           corrupted due to not being updated — any references to other commit
580           hashes in commit messages will now refer to no-longer-extant
581           commits.
582
583       •   There are no facilities for helping users find what unwanted crud
584           they should delete, which means they are much more likely to have
585           incomplete or partial cleanups that sometimes result in confusion
586           and people wasting time trying to understand. (For example, folks
587           tend to just look for big files to delete instead of big
588           directories or extensions, and once they do so, then sometime later
589           folks using the new repository who are going through history will
590           notice a build artifact directory that has some files but not
591           others, or a cache of dependencies (node_modules or similar) which
592           couldn’t have ever been functional since it’s missing some files.)
593
594       •   If --prune-empty isn’t specified, then the filtering process can
595           create hoards of confusing empty commits
596
597       •   If --prune-empty is specified, then intentionally placed empty
598           commits from before the filtering operation are also pruned instead
599           of just pruning commits that became empty due to filtering rules.
600
601       •   If --prune-empty is specified, sometimes empty commits are missed
602           and left around anyway (a somewhat rare bug, but it happens...)
603
604       •   A minor issue, but users who have a goal to update all names and
605           emails in a repository may be led to --env-filter which will only
606           update authors and committers, missing taggers.
607
608       •   If the user provides a --tag-name-filter that maps multiple tags to
609           the same name, no warning or error is provided; git-filter-branch
610           simply overwrites each tag in some undocumented pre-defined order
611           resulting in only one tag at the end. (A git-filter-branch
612           regression test requires this surprising behavior.)
613
614       Also, the poor performance of git-filter-branch often leads to safety
615       issues:
616
617       •   Coming up with the correct shell snippet to do the filtering you
618           want is sometimes difficult unless you’re just doing a trivial
619           modification such as deleting a couple files. Unfortunately, people
620           often learn if the snippet is right or wrong by trying it out, but
621           the rightness or wrongness can vary depending on special
622           circumstances (spaces in filenames, non-ascii filenames, funny
623           author names or emails, invalid timezones, presence of grafts or
624           replace objects, etc.), meaning they may have to wait a long time,
625           hit an error, then restart. The performance of git-filter-branch is
626           so bad that this cycle is painful, reducing the time available to
627           carefully re-check (to say nothing about what it does to the
628           patience of the person doing the rewrite even if they do
629           technically have more time available). This problem is extra
630           compounded because errors from broken filters may not be shown for
631           a long time and/or get lost in a sea of output. Even worse, broken
632           filters often just result in silent incorrect rewrites.
633
634       •   To top it all off, even when users finally find working commands,
635           they naturally want to share them. But they may be unaware that
636           their repo didn’t have some special cases that someone else’s does.
637           So, when someone else with a different repository runs the same
638           commands, they get hit by the problems above. Or, the user just
639           runs commands that really were vetted for special cases, but they
640           run it on a different OS where it doesn’t work, as noted above.
641

GIT

643       Part of the git(1) suite
644

NOTES

646        1. git filter-repo
647           https://github.com/newren/git-filter-repo/
648
649        2. filter-lamely
650           https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely
651
652
653
654Git 2.33.1                        2021-10-12              GIT-FILTER-BRANCH(1)
Impressum