view doc/README @ 16777:058e14da7044

graphlog: turn getlogrevs() into a generator

This improves the poor "time to first changeset" compared to the
original log command. When running:

  $ hg log -u user

log will enumerate the changelog and display matching revisions when
they are found. But:

  $ hg log -G -u user

will first find all revisions matching the user then start to display
them.

Initially, I considered turning revset.match() into a generator. This is
doable but requires a fair amount of work. Instead,
cmdutil.increasingwindows() is reused to call the revset matcher
repeatedly. This has the nice properties of:
- Let us reorder the windows after filtering, which is necessary as the
  matcher can reorder inputs but is an internal detail not a feature.
- Let us feed the matcher with windows in changelog order, which is good
  for performances.
- Have a generator designed for log-like commands, returning small
  windows at first then batching larger ones.

I feel that calling the matcher multiple times is correct, at least with
the revsets involved in getlogrevs() because they are:
- stateless (no limit())
- respecting f(a|b) = f(a) | f(b), though I have no valid argument about
  that.

Known issues compared to log code:
- Calling the revset matcher multiple times can be slow when revset
  functions have to create expensive data structure for filtering. This
  will be addressed in a followup.
- Predicate combinations like "--user foo --user bar" or "--user foo and
  --branch bar" are inherently slower because all input revision are
  checked against the first condition, then against the second, and so
  forth. log would enumerate the input revisions once and check each of
  them once against all conditions, which is faster. There are solutions
  but nothing cheap to implement.

Some numbers against mozilla repository:

                             first line    total

  * hg log -u rnewman
  /Users/pmezard/bin/hg-2.2      0.148s   7.293s
  /Users/pmezard/bin/hgdev       0.132s   5.747s

  * hg log -u rnewman -u girard
  /Users/pmezard/bin/hg-2.2      0.146s   7.323s
  /Users/pmezard/bin/hgdev       0.136s  11.096s

  * hg log -l 10
  /Users/pmezard/bin/hg-2.2      0.137s   0.153s
  /Users/pmezard/bin/hgdev       0.128s   0.144s

  * hg log -l 10 -u rnewman
  /Users/pmezard/bin/hg-2.2      0.146s   0.265s
  /Users/pmezard/bin/hgdev       0.133s   0.236s

  * hg log -b GECKO193a2_20100228_RELBRANCH
  /Users/pmezard/bin/hg-2.2      2.332s   6.618s
  /Users/pmezard/bin/hgdev       1.972s   5.543s

  * hg log xulrunner
  /Users/pmezard/bin/hg-2.2      5.829s   5.958s
  /Users/pmezard/bin/hgdev       0.194s   6.017s

  * hg log --follow xulrunner/build.mk
  /Users/pmezard/bin/hg-2.2      0.353s   0.438s
  /Users/pmezard/bin/hgdev       0.394s   0.580s

  * hg log -u girard tools
  /Users/pmezard/bin/hg-2.2      5.853s   6.012s
  /Users/pmezard/bin/hgdev       0.195s   6.030s

  * hg log -b COMM2000_20110314_RELBRANCH --copies
  /Users/pmezard/bin/hg-2.2      2.231s   6.653s
  /Users/pmezard/bin/hgdev       1.897s   5.585s

  * hg log --follow
  /Users/pmezard/bin/hg-2.2      0.137s  14.140s
  /Users/pmezard/bin/hgdev       0.381s  44.246s

  * hg log --follow -r 80000:90000
  /Users/pmezard/bin/hg-2.2      0.127s   1.611s
  /Users/pmezard/bin/hgdev       0.147s   1.847s

  * hg log --follow -r 90000:80000
  /Users/pmezard/bin/hg-2.2      0.130s   1.702s
  /Users/pmezard/bin/hgdev       0.368s   6.106s

  * hg log --follow -r 80000:90000 js/src/jsproxy.cpp
  /Users/pmezard/bin/hg-2.2      0.343s   0.388s
  /Users/pmezard/bin/hgdev       0.437s   0.631s

  * hg log --follow -r 90000:80000 js/src/jsproxy.cpp
  /Users/pmezard/bin/hg-2.2      0.342s   0.389s
  /Users/pmezard/bin/hgdev       0.442s   0.628s

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.