view tests/test-userguide.t @ 978:8328337d23b2

docs: add new user guide

This has also been reviewed to death on evolve-testers. There are
still a couple of short sections to write (clearly marked "TODO"), and
one example to add. But (if I may be so bold) this is a gigantic
improvement over the current docs, so it really should get merged.

Incidentally, the figures are all SVG files created with Inkscape.
They're not perfect, but they're pretty nice. Anyone who knows a
better way to create technical diagrams is welcome to contribute.

One wart: there's a test script that accompanies the document and
largely duplicates it, but I haven't unified them. I've been
concentrating on writing the best possible content, not on fiddling
with tools. I suspect that unifying them will be non-trivial, but
definitely worth doing.

ensure that all the scenarios in the user guide work as documented

basic repo
  $ hg init t
  $ cd t
  $ touch file1.c file2.c
  $ hg -q commit -A -m init

example 1: commit creates a changeset in draft phase
(this is nothing to do with evolve, but it's mentioned in the user guide)
  $ echo 'feature Y' >> file1.c
  $ hg commit -u alice -d '0 0' -m 'implement feature X'
  $ hg phase -r .
  1: draft
  $ hg identify -in
  6e725fd2be6f 1

example 2: unsafe amend with plain vanilla Mercurial: the original
commit is stripped
  $ hg commit --amend -u alice -d '1 0' -m 'implement feature Y'
  saved backup bundle to $TESTTMP/t/.hg/strip-backup/6e725fd2be6f-amend-backup.hg
  $ hg log -r 23fe4ac6d3f1
  abort: unknown revision '23fe4ac6d3f1'!
  [255]
  $ hg identify -in
  fe0ecd3bd2a4 1

enable evolve for safe history modification
  $ cat >> $HGRCPATH <<EOF
  > [alias]
  > shortlog = log --template '{rev}:{node|short}  {phase}  {desc|firstline}\n'
  > [extensions]
  > rebase =
  > EOF
  $ echo "evolve=$(echo $(dirname $TESTDIR))/hgext/evolve.py" >> $HGRCPATH

example 3: safe amend with "hg commit --amend" (figure 2)
  $ echo 'tweak feature Y' >> file1.c
  $ hg commit --amend -u alice -d '2 0' -m 'implement feature Y'
  $ hg shortlog -q -r fe0ecd3bd2a4
  abort: unknown revision 'fe0ecd3bd2a4'!
  [255]
  $ hg --hidden shortlog -G
  @  3:934359450037  draft  implement feature Y
  |
  | x  2:6c5f78d5d467  draft  temporary amend commit for fe0ecd3bd2a4
  | |
  | x  1:fe0ecd3bd2a4  draft  implement feature Y
  |/
  o  0:08c4b6f4efc8  draft  init
  
example 3 redux: repeat safe amend, this time with "hg amend"
  $ hg rollback -q
  $ hg amend -u alice -d '2 0' -m 'implement feature Y'
  $ hg --hidden shortlog -G
  @  3:934359450037  draft  implement feature Y
  |
  | x  2:6c5f78d5d467  draft  temporary amend commit for fe0ecd3bd2a4
  | |
  | x  1:fe0ecd3bd2a4  draft  implement feature Y
  |/
  o  0:08c4b6f4efc8  draft  init
  
example 4: prune at head (figure 3)
  $ echo 'debug hack' >> file1.c
  $ hg commit -m 'debug hack'
  $ hg prune .
  1 changesets pruned
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  working directory now at 934359450037
  $ hg parents --template '{rev}:{node|short}  {desc|firstline}\n'
  3:934359450037  implement feature Y
  $ hg --hidden shortlog -G -r 3:
  x  4:a3e0ef24aaf0  draft  debug hack
  |
  @  3:934359450037  draft  implement feature Y
  |

example 5: uncommit files at head (figure 4)
  $ echo 'relevant' >> file1.c
  $ echo 'irrelevant' >> file2.c
  $ hg commit -u dan -d '10 0' -m 'fix bug 234'
  $ hg uncommit file2.c
  $ hg status
  M file2.c
  $ hg --hidden shortlog -G -r 'descendants(3) - 4'
  @  6:c8defeecf7a4  draft  fix bug 234
  |
  | x  5:da4331967f5f  draft  fix bug 234
  |/
  o  3:934359450037  draft  implement feature Y
  |
  $ hg parents --template '{rev}:{node|short}  {desc|firstline}\n{files}\n'
  6:c8defeecf7a4  fix bug 234
  file1.c
  $ hg revert --no-backup file2.c

example 6: fold multiple changesets together into one (figure 5)
  $ echo step1 >> file1.c
  $ hg commit -m 'step 1'
  $ echo step2 >> file1.c
  $ hg commit -m 'step 2'
  $ echo step3 >> file2.c
  $ hg commit -m 'step 3'
  $ hg log --template '{rev}:{node|short}  {desc|firstline}\n' -r 7::
  7:05e61aab8294  step 1
  8:be6d5bc8e4cc  step 2
  9:35f432d9f7c1  step 3
  $ hg fold -d '0 0' -m 'fix bug 64' -r 7::
  3 changesets folded
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg --hidden shortlog -G -r 6::
  @  10:171c6a79a27b  draft  fix bug 64
  |
  | x  9:35f432d9f7c1  draft  step 3
  | |
  | x  8:be6d5bc8e4cc  draft  step 2
  | |
  | x  7:05e61aab8294  draft  step 1
  |/
  o  6:c8defeecf7a4  draft  fix bug 234
  |
  $ hg --hidden log -q -r 'successors(7) | successors(8) | successors(9)'
  10:171c6a79a27b
  $ hg --hidden log -q -r 'precursors(10)'
  7:05e61aab8294
  8:be6d5bc8e4cc
  9:35f432d9f7c1
  $ hg diff -c 10 -U 0
  diff -r c8defeecf7a4 -r 171c6a79a27b file1.c
  --- a/file1.c	Thu Jan 01 00:00:10 1970 +0000
  +++ b/file1.c	Thu Jan 01 00:00:00 1970 +0000
  @@ -3,0 +4,2 @@
  +step1
  +step2
  diff -r c8defeecf7a4 -r 171c6a79a27b file2.c
  --- a/file2.c	Thu Jan 01 00:00:10 1970 +0000
  +++ b/file2.c	Thu Jan 01 00:00:00 1970 +0000
  @@ -0,0 +1,1 @@
  +step3

setup for example 7: amend an older changeset
  $ echo 'fix fix oops fix' > file2.c
  $ hg commit -u bob -d '3 0' -m 'fix bug 17'
  $ echo 'cleanup' >> file1.c
  $ hg commit -u bob -d '4 0' -m 'cleanup'
  $ echo 'new feature' >> file1.c
  $ hg commit -u bob -d '5 0' -m 'feature 23'
  $ hg --hidden shortlog -G -r 10::
  @  13:dadcbba2d606  draft  feature 23
  |
  o  12:debd46bb29dc  draft  cleanup
  |
  o  11:3e1cb8f70c02  draft  fix bug 17
  |
  o  10:171c6a79a27b  draft  fix bug 64
  |

example 7: amend an older changeset (figures 6, 7)
  $ hg update -q 11
  $ echo 'fix fix fix fix' > file2.c
  $ hg amend -u bob -d '6 0'
  2 new unstable changesets
  $ hg shortlog -r 'obsolete()'
  11:3e1cb8f70c02  draft  fix bug 17
  $ hg shortlog -r 'unstable()'
  12:debd46bb29dc  draft  cleanup
  13:dadcbba2d606  draft  feature 23
  $ hg --hidden shortlog -G -r 10::
  @  15:395cbeda3a06  draft  fix bug 17
  |
  | x  14:f7fab707e247  draft  temporary amend commit for 3e1cb8f70c02
  | |
  | | o  13:dadcbba2d606  draft  feature 23
  | | |
  | | o  12:debd46bb29dc  draft  cleanup
  | |/
  | x  11:3e1cb8f70c02  draft  fix bug 17
  |/
  o  10:171c6a79a27b  draft  fix bug 64
  |
  $ hg evolve -q --all
  $ hg shortlog -G -r 10::
  @  17:91b4b0f8b5c5  draft  feature 23
  |
  o  16:fe8858bd9bc2  draft  cleanup
  |
  o  15:395cbeda3a06  draft  fix bug 17
  |
  o  10:171c6a79a27b  draft  fix bug 64
  |

setup for example 8: prune an older changeset (figure 8)
  $ echo 'useful' >> file1.c
  $ hg commit -u carl -d '7 0' -m 'useful work'
  $ echo 'debug' >> file2.c
  $ hg commit -u carl -d '8 0' -m 'debug hack'
  $ echo 'more useful' >> file1.c
  $ hg commit -u carl -d '9 0' -m 'more work'
  $ hg shortlog -G -r 17::
  @  20:ea8fafca914b  draft  more work
  |
  o  19:b23d06b457a8  draft  debug hack
  |
  o  18:1f33e68b18b9  draft  useful work
  |
  o  17:91b4b0f8b5c5  draft  feature 23
  |

example 8: prune an older changeset (figures 8, 9)
  $ hg prune 19
  1 changesets pruned
  1 new unstable changesets
  $ hg --hidden shortlog -G -r 18::
  @  20:ea8fafca914b  draft  more work
  |
  x  19:b23d06b457a8  draft  debug hack
  |
  o  18:1f33e68b18b9  draft  useful work
  |
  $ hg evolve -q --all
  $ hg --hidden shortlog -G -r 18::
  @  21:4393e5877437  draft  more work
  |
  | x  20:ea8fafca914b  draft  more work
  | |
  | x  19:b23d06b457a8  draft  debug hack
  |/
  o  18:1f33e68b18b9  draft  useful work
  |

example 9: uncommit files from an older changeset (discard changes)
(figure 10)
  $ echo 'this fixes bug 53' >> file1.c
  $ echo 'debug hack' >> file2.c
  $ hg commit -u dan -d '11 0' -m 'fix bug 53'
  $ echo 'and this handles bug 67' >> file1.c
  $ hg commit -u dan -d '12 0' -m 'fix bug 67'
  $ hg update 22
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg shortlog -G -r 21::
  o  23:4db2428c8ae3  draft  fix bug 67
  |
  @  22:f84357446753  draft  fix bug 53
  |
  o  21:4393e5877437  draft  more work
  |
  $ hg uncommit file2.c
  1 new unstable changesets
  $ hg status
  M file2.c
  $ hg revert file2.c
  $ hg evolve --all
  move:[23] fix bug 67
  atop:[24] fix bug 53
  $ hg --hidden shortlog -G -r 21::
  @  25:0d972d6888e6  draft  fix bug 67
  |
  o  24:71bb83d674c5  draft  fix bug 53
  |
  | x  23:4db2428c8ae3  draft  fix bug 67
  | |
  | x  22:f84357446753  draft  fix bug 53
  |/
  o  21:4393e5877437  draft  more work
  |
  $ rm file2.c.orig

example 10: uncommit files from an older changeset (keep changes)
(figures 11, 12)
  $ echo 'fix a bug' >> file1.c
  $ echo 'useful but unrelated' >> file2.c
  $ hg commit -u dan -d '11 0' -m 'fix a bug'
  $ echo 'new feature' >> file1.c
  $ hg commit -u dan -d '12 0' -m 'new feature'
  $ hg update 26
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg --hidden shortlog -G -r 25::
  o  27:fbb3c6d50427  draft  new feature
  |
  @  26:5b31a1239ab9  draft  fix a bug
  |
  o  25:0d972d6888e6  draft  fix bug 67
  |
  $ hg uncommit file2.c
  1 new unstable changesets
  $ hg status
  M file2.c
  $ hg commit -m 'useful tweak'
  $ hg --hidden shortlog -G -r 25::
  @  29:51e0d8c0a922  draft  useful tweak
  |
  o  28:2594e98553a9  draft  fix a bug
  |
  | o  27:fbb3c6d50427  draft  new feature
  | |
  | x  26:5b31a1239ab9  draft  fix a bug
  |/
  o  25:0d972d6888e6  draft  fix bug 67
  |
  $ hg evolve --all
  move:[27] new feature
  atop:[28] fix a bug
  $ hg --hidden shortlog -G -r 25::
  @  30:166c1c368ab6  draft  new feature
  |
  | o  29:51e0d8c0a922  draft  useful tweak
  |/
  o  28:2594e98553a9  draft  fix a bug
  |
  | x  27:fbb3c6d50427  draft  new feature
  | |
  | x  26:5b31a1239ab9  draft  fix a bug
  |/
  o  25:0d972d6888e6  draft  fix bug 67
  |