Version Control with Git, 2nd Edition

Chapter 19. Advanced Manipulations

Using git filter-branch

The command git filter-branch is a generic branch processing command that allows you to arbitrarily rewrite the commits of a branch using custom commands that operate on different objects within the repository. Some filters work on commits, some filters on tree objects and directory structures, and others provide environmental manipulation opportunity.

Does that sound useful and yet dangerous?

Good.

As you might suspect, with great power comes great responsibility.^[40] The power and purpose of filter-branch is also the source of my warning: it has the potential to rewrite the entire repository’s commit history. Executing this command on a repository that has already been published for others to clone and use will likely cause them endless grief later. As with all rebasing operations, commit history will change. After this command, you should consider any repositories cloned from it earlier as obsolete.

With that warning about rewriting repository history behind us, let’s find out what the command can do, when and why it might be useful, and how to use it responsibly.

The filter-branch command runs a series of filters on one or more branches within your repository. Each filter can have its own custom filtering command. You don’t have to run them all, or even more than one. But they are designed and sequenced so that earlier filters can affect the behavior of later filters. The subdirectory-filter runs as a precommit-processing ...