1GIT-FILTER-BRANCH(1) Git Manual GIT-FILTER-BRANCH(1)
2
3
4
6 git-filter-branch - Rewrite branches
7
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
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
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
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
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
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
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
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
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
643 Part of the git(1) suite
644
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.30.2 2021-03-08 GIT-FILTER-BRANCH(1)