GIT: Rewriting commit history with git filter-branch

48.1. Using the git filter branch command (filter-branch)

The git filter-branch command allows you to rewrite the Git commit history. This can be done for selected branches and you can apply custom filters on each revision. This creates different hashes for all modified commits. This implies that you get new IDs for all commits based on any rewritten commit.

The command allows you to filter for several values, e.g., the author, the message, etc. 

Using the filter-branch command is dangerous as it changes the Git repository.  It changes the commit IDs and reacting on such a change requires explicit action  from the developer, e.g., trying to rebase the stale local branch onto the  corresponding rewritten remote-tracking branch.

For example, you can use git filter-branch if you want to remove a file which contains a password from the Git history. Or you want to remove huge binary files from the history. To completely remove such files, you need to run the filter-branch command on all branches.

48.2. filter-branch examples

The following command extracts a directory from a Git repository and retains all commits for this subfolder.

git filter-branch --prune-empty --subdirectory-filter FOLDER-NAME  BRANCH-NAME

The following command replaces the email address of one author from all commits.

git filter-branch -f \
--env-filter 'if [ "$GIT_AUTHOR_NAME" = "Lars Vogel" ]; then \
GIT_AUTHOR_EMAIL="lars.vogel@gmail.com"; fi' HEAD)