Removing files from Mercurial history

Another post for developers reading this blog. If you think these posts do not belong here, please leave a comment, and I'll consider moving my development articles to a separate blog.

Sometimes you need to remove files from Mercurial completely, even from the history. For instance, if you have mistakenly stored a sensitive file in the repo (some password, or an access key, or a code-signing certificate etc. etc.) Here's how you do it:

Background: the "Convert" extension

You will need the "hg convert" command. This command is normally used to convert an SVN/GIT repository to Mercurial, but it can be used to "convert" from Mercurial to Mercurial as well. The great thing about this command is the "--filemap" option that specifies which files should be included in the conversion process and which should not.

Steps to remove a file from hg

1. Make sure all your teammates have pushed their local changes to the central repo (if any)
2. Backup your repository
3. Create a "map.txt" file:

   # this filemap is used to exclude specific files
   exclude "subdir/filename1.ext"
   exclude "subdir/filename2.ext"
   exclude "subdir2"

4. Run this command:
   hg convert --filemap map.txt c:/oldrepo c:/newrepo
   NOTE: You have to use "forward-slash" in paths, even on windows.
5. Wait and be patient
6. Now you have a new repo at c:\newrepo but without the files

(optional) Pushing your new repo back to central repo (e.g. Bitbucket)

If you have some central hg-storage you will have to "strip" all your changesets and then "push" your local repostiroy again.

For instance, if you use Bitbucket like us, go to "Admin - Strip". Enter "0" into the "Revision" box and this will remove all commits, but the "wiki" and "issues" areas will be preserved. Then - push the local repo back to Bitbucket again.

There's a trick!

Because the above procedure affects history and re-assigns new "ids" to all your changesets, your teammates have to reclone the repo from the central repo again!