annotate doc/README @ 16509:eab9119c5dee stable

rebase: skip resolved but emptied revisions

When rebasing, if a conflict occurs and is resolved in a way the rebased
revision becomes empty, it is not skipped, unlike revisions being emptied
without conflicts.

The reason is:
- File 'x' is merged and resolved, merge.update() marks it as 'm' in the
  dirstate.
- rebase.concludenode() calls localrepo.commit(), which calls
  localrepo.status() which calls dirstate.status(). 'x' shows up as 'm' and is
  unconditionnally added to the modified files list, instead of being checked
  again.
- localrepo.commit() detects 'x' as changed an create a new revision where only
  the manifest parents and linkrev differ.

Marking 'x' as modified without checking it makes sense for regular merges. But
in rebase case, the merge looks normal but the second parent is usually
discarded. When this happens, 'm' files in dirstate are a bit irrelevant and
should be considered 'n' possibly dirty instead. That is what the current patch
does.

Another approach, maybe more efficient, would be to pass another flag to
merge.update() saying the 'branchmerge' is a bit of a lie and recordupdate()
should call dirstate.normallookup() instead of merge().

It is also tempting to add this logic to dirstate.setparents(), moving from two
to one parent is what invalidates the 'm' markers. But this is a far bigger
change to make.

v2: succumb to the temptation and move the logic in dirstate.setparents(). mpm
suggested trying _filecommit() first but it is called by commitctx() which
knows nothing about the dirstate and comes too late into the game. A second
approach was to rewrite the 'm' state into 'n' on the fly in dirstate.status()
which failed for graft in the following case:

  $ hg init repo
  $ cd repo
  $ echo a > a
  $ hg ci -qAm0
  $ echo a >> a
  $ hg ci -m1
  $ hg up 0
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg mv a b
  $ echo c > b
  $ hg ci -m2
  created new head
  $ hg graft 1 --tool internal:local
  grafting revision 1
  $ hg --config extensions.graphlog= glog --template '{rev} {desc|firstline}\n'
  @  3 1
  |
  o  2 2
  |
  | o  1 1
  |/
  o  0 0

  $ hg log -r 3 --debug --patch --git --copies
  changeset:   3:19cd7d1417952af13161b94c32e901769104560c
  tag:         tip
  phase:       draft
  parent:      2:b5c505595c9e9a12d5dd457919c143e05fc16fb8
  parent:      -1:0000000000000000000000000000000000000000
  manifest:    3:3d27ce8d02241aa59b60804805edf103c5c0cda4
  user:        test
  date:        Thu Jan 01 00:00:00 1970 +0000
  extra:       branch=default
  extra:       source=a03df74c41413a75c0a42997fc36c2de97b26658
  description:
  1

Here, revision 3 is created because there is a copy record for 'b' in the
dirstate and thus 'b' is considered modified. But this information is discarded
at commit time since 'b' content is unchanged. I do not know if discarding this
information is correct or not, but at this time we cannot represent it anyway.

This patch therefore implements the last solution of moving the logic into
dirstate.setparents(). It does not sound crazy as 'm' files makes no sense with
only one parent. It also makes dirstate.merge() calls .lookupnormal() if there
is one parent, to preserve the invariant.

I am a bit concerned about introducing this kind of stateful behaviour to
existing code which historically treated setparents() as a basic setter without
side-effects. And doing that during the code freeze.

Mercurial's documentation is kept in reStructuredText format, which is
a simple plain text format that's easy to read and edit:

  http://docutils.sourceforge.net/rst.html

It's also convertible to a variety of other formats including standard
UNIX man page format and HTML. You'll need to install Docutils:

  http://docutils.sourceforge.net/

Use the Makefile in this directory to generate the man and HTML pages.