repo sync --force-sync overwrites your existing repository!

I couldn't find any good explanation of what does Android's repo's --force-sync do, nor why it can be needed. So I'm reporting my painful findings in repo 1.22.

Looks like repo keeps track of the repositories that it has init'ed. So if you created a repository independently of repo, and then add an entry for that existing repository to the repo manifest, repo sync will choke and present you with the message:
error.GitError: --force-sync not enabled; cannot overwrite a local work tree. If you're comfortable with the possibility of losing the work tree's git metadata, use `repo sync --force-sync mydirectory` to proceed.
Turns out that "git metadata" means the whole .git directory inside mydirectory [1]. So, any branch, any stash, anything in your existing local repository will be destroyed. No recourse to reflog, either!

Once  you have run repo --force-sync, the repository will be accepted by repo on further repo sync calls.

An alternative to using --force-sync might have been to use --force-break (or simply -f), which just goes on when any directory fails to sync. But I didn't try, and I don't know how that would even make sense if we assume that repo doesn't go into a directory it didn't create.

It's not easy to find docs for repo online. Turns out that it includes its own documentation; try "repo help sync".

[1] When I stumbled upon this, I thought that "git metadata" would mean a git branch head or something like that; I assumed that repo would play inside the git repository that was already there! The mild language ("comfortable with the possibility") sounded like any consequence could be, well, mild. Alas, no. Was it so difficult to say "This will overwrite your .git directory" or something as clear as that? ... or maybe there are cases more nuanced than mine?


  1. I think whole git-repo idea is a step backward.. closer to an ancient CVS

  2. I'd like to know how/where do I have to enable --force-sync flag - currently it fails to overwrite the repo. I use "repo sync --force-sync".

    1. Sorry, I just realized that you wrote long ago. Anyway, I am not sure I could help; "repo sync --force-sync" is exactly what you have to use. If you had reported what exactly happened at that point maybe I could say something more...