--force-sync trouble and suggestions

[H. Mijail Antón Quiles]

I just lost some data because of repo sync --force-sync. The only online half-explanation of what --force-sync does was a thread from 2015 in this group, and "repo help sync" didn't help much either.

So I would like to suggest an improvement to the help text and/or to the error text that suggests using --force-sync.

For context: I had been using repo with a manifest which defined 4 repositories. I cloned manually 2 new repositories and worked with them for some time. The problem came when later I added the 2 new repositories to the repo manifest: "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."

At this point I was assuming (before you joke, please tell me how it wasn't reasonable ;P) that repo would try working with the git data already present in mydirectory; so "git metadata" sounded like maybe git branch heads, which anyway I already expected to be changed by repo. Furthermore, the mild language in repo's suggestion ("if you're comfortable with the possibility") made me think that any consequence would be mild too (meaning, fixable through the reflog).
But --force-sync just overwrote my whole repository! So, when it was already too late, I realized that repo didn't even try using the existing git data; and that "git metadata" rather meant the whole .git directory inside mydirectory.

So: I'd suggest for the help text and/or the error text to be much more clear about what is going to happen. For example: "To overwrite the existing directory mydirectory with the cloned git repository myrepository, use --force-sync."

I already wrote a short blog post about this, but I figured that posting a comment here might be more useful in the long run.