Founder's blog

Removing files from Mercurial history

Mar 24 2014 :: by Alex
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!

'Removing files from Mercurial history' was written by Alex by Alex. CEO, founder