view CONTRIBUTING @ 30151:381293e1135e

copy: distinguish "file exists" cases and add a hint (BC)

Users that want to add a copy record to an existing commit with 'hg
commit --amend' should be guided towards this workflow, rather than
reaching for some sort of uncommit-recommit flow. As part of this,
distinguish in the top-line error message whether the file merely
already exists (untracked) on disk or the file already exists in
history.

The full list of copy and rename cases and how they interact with
flags are listed below:

target exists  --after  --force  |  action
      n            n      *    |  copy
      n            y      *    |  (1)
  untracked        n      n    |  (4) NEWHINT
  untracked        n      y    |  (3)
  untracked        y      *    |  (2)
      y            n      n    |  (4) NEWHINT
      y            n      y    |  (3)
      y            y      n    |  (2)
      y            y      y    |  (3)
   deleted         n      n    |  copy
   deleted         n      y    |  (3)
   deleted         y      n    |  (1)
   deleted         y      y    |  (1)

* = don't care
(1) <src>: not recording move - <target> does not exist
(2) preserve target contents
(3) replace target contents
(4) <target>: not overwriting - file {exists,already committed}

Credit to Kevin for wholly rewriting my table to cover more cases we
discovered at the sprint.

I think this change gets the hints correct in all cases, but I'd
appreciate close inspection of the test cases to make sure I haven't
gotten turned around in here.

Our full contribution guidelines are in our wiki, please see:

https://www.mercurial-scm.org/wiki/ContributingChanges

If you just want a checklist to follow, you can go straight to

https://www.mercurial-scm.org/wiki/ContributingChanges#Submission_checklist

If you can't run the entire testsuite for some reason (it can be
difficult on Windows), please at least run `contrib/check-code.py` on
any files you've modified and run `python contrib/check-commit` on any
commits you've made (for example, `python contrib/check-commit
273ce12ad8f1` will report some style violations on a very old commit).