When do you need `--tag-name-filter cat` for `git filter-branch`?

Question

The man page of git filter branch says:

use \"--tag-name-filter cat\" to simply update the tags.

Later it even says:

Answer 1

You need '--tag-name-filter' for git filter-branch any time you want it to actually update/create your tags - rather than just create rewritten commits those tags point to. The command you supply the switch is a shell script that gets the old tag name as input, and git-filter-branch uses the command passed to '--tag-name-filter' to work out what you want the new tag name to be.

For instance, if you had a tag called 'work-by-sun' and used '--tag-name-filter sed s/sun/oracle/', then instead of updating the tag, a new tag would be created called 'work-by-oracle'.

More normally, if you use '--tag-name-filter cat', the command is just cat, and the tag name used is the same as the original tag - so the tag is overwritten to point to the new commit.

The '--all' part of the command-line arguments specifies what refs should get rewritten, but tags won't get updated unless you use the --tag-name-filter parameter.

If all this seems a bit fiddly, you may want to consider if you can achieve what you want using the BFG Repo-Cleaner.

Full disclosure: I'm the author of the BFG Repo-Cleaner.