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
17

WARNING

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

DESCRIPTION

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

OPTIONS

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

EXIT STATUS

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

EXAMPLES

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

CHECKLIST FOR SHRINKING A REPOSITORY

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

PERFORMANCE

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

SAFETY

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

GIT

659       Part of the git(1) suite
660

NOTES

662        1. git filter-repo
663           https://github.com/newren/git-filter-repo/
664
665        2. filter-lamely
666           https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely
667
668
669
670Git 2.24.1                        12/10/2019              GIT-FILTER-BRANCH(1)
Impressum