annotate doc/README @ 25878:800e090e9c64 stable

localrepo: make journal.dirstate contain in-memory changes before transaction

Before this patch, in-memory dirstate changes aren't written out at
opening transaction, even though 'journal.dirstate' is created
directly from '.hg/dirstate'.

Therefore, subsequent 'hg rollback' uses incomplete 'undo.dirstate' to
restore dirstate, if dirstate is changed and isn't written out before
opening transaction.

In cases below, the condition "dirstate is changed and isn't written
out before opening transaction" isn't satisfied and this problem
doesn't appear:

  - "wlock scope" and "transaction scope" are almost equivalent

    e.g. 'commit --amend', 'import' and so on

  - dirstate changes are written out before opening transaction

    e.g. 'rebase' (via 'dirstateguard') and 'commit -A' (by separated
    wlock scopes)

On the other hand, 'backout' may satisfy the condition above.

To make 'journal.dirstate' contain in-memory changes before opening
transaction, this patch explicitly invokes 'dirstate.write()' in
'localrepository.transaction()'.

'dirstate.write()' is placed before not "writing journal files out"
but "invoking pretxnopen hooks" for visibility of dirstate changes to
external hook processes.

BTW, in the test script, 'touch -t 200001010000' and 'hg status' are
invoked to make file 'c' surely clean in dirstate, because "clean but
unsure" files indirectly cause 'dirstate.write()' at 'repo.status()'
in 'repo.commit()' (see fe03f522dda9 for detail) and prevents from
certainly reproducing the issue.

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.