docs/sharing.rst
author Pierre-Yves David <pierre-yves.david@octobus.net>
Sat, 01 Feb 2020 12:50:10 +0100
changeset 5111 1fe3f7ffb462
parent 4973 f3faafa1e064
permissions -rw-r--r--
branching
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     1
.. Copyright © 2014 Greg Ward <greg@gerg.ca>
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     2
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     3
------------------------------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     4
Evolve: Shared Mutable History
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     5
------------------------------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     6
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
     7
.. contents::
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
     8
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     9
Once you have mastered the art of mutable history in a single
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    10
repository (see the `user guide`_), you can move up to the next level:
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    11
*shared* mutable history. ``evolve`` lets you push and pull draft
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    12
changesets between repositories along with their obsolescence markers.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    13
This opens up a number of interesting possibilities.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    14
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    15
.. _`user guide`: user-guide.html
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    16
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    17
The simplest scenario is a single developer working across two
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    18
computers. Say you're working on code that must be tested on a remote
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    19
test server, probably in a rack somewhere, only accessible by SSH, and
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    20
running an “enterprise-grade” (out-of-date) OS. But you probably
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    21
prefer to write code locally: everything is setup the way you like it,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    22
and you can use your preferred editor, IDE, merge/diff tools, etc.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    23
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    24
Traditionally, your options are limited: either
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    25
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    26
  * (ab)use your source control system by committing half-working code
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    27
    in order to get it onto the remote test server, or
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    28
  * go behind source control's back by using ``rsync`` (or similar) to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    29
    transfer your code back-and-forth until it is ready to commit
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    30
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    31
The former is less bad with distributed version control systems like
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    32
Mercurial, but it's still far from ideal. (One important version
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    33
control “best practice” is that every commit should make things just a
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    34
little bit better, i.e. you should never commit code that is worse
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    35
than what came before.) The latter, avoiding version control entirely,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    36
means that you're walking a tightrope without a safety net. One
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    37
accidental ``rsync`` in the wrong direction could destroy hours of
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    38
work.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    39
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    40
Using Mercurial with ``evolve`` to share mutable history solves these
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    41
problems. As with single-repository ``evolve``, you can commit
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    42
whenever the code is demonstrably better, even if all the tests aren't
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    43
passing yet—just ``hg amend`` when they are. And you can transfer
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    44
those half-baked changesets between repositories to try things out on
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    45
your test server before anything is carved in stone.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    46
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    47
A less common scenario is multiple developers sharing mutable history,
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
    48
typically for code review. We'll cover this scenario later. First, we
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
    49
will cover single-user sharing.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    50
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
    51
Sharing with a single developer
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
    52
-------------------------------
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
    53
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    54
Publishing and non-publishing repositories
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
    55
==========================================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    56
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    57
The key to shared mutable history is to keep your changesets in
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
    58
*draft* phase as you pass them around. Recall that by default,
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
    59
``hg push`` promotes changesets from *draft* to *public*, and public
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    60
changesets are immutable. You can change this behaviour by
2863
3e3a276c9e91 doc: reword "target repository" to "remote repository"
Philippe Pepiot <phil@philpep.org>
parents: 2862
diff changeset
    61
reconfiguring the *remote* repository so that it is non-publishing.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    62
(Short version: set ``phases.publish`` to ``false``. Long version
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    63
follows.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    64
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
    65
Setting up
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
    66
==========
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    67
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    68
We'll work through an example with three local repositories, although
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    69
in the real world they'd most likely be on three different computers.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    70
First, the ``public`` repository is where tested, polished changesets
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    71
live, and it is where you synchronize with the rest of your team. ::
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    72
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    73
  $ hg init public
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    74
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    75
We'll need two clones where work gets done, ``test-repo`` and
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    76
``dev-repo``::
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    77
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    78
  $ hg clone public test-repo
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    79
  updating to branch default
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    80
  0 files updated, 0 files merged, 0 files removed, 0 files unresolved
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    81
  $ hg clone test-repo dev-repo
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    82
  updating to branch default
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    83
  0 files updated, 0 files merged, 0 files removed, 0 files unresolved
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    84
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    85
``dev-repo`` is your local machine, with GUI merge tools and IDEs and
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    86
everything configured just the way you like it. ``test-repo`` is the
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    87
test server in a rack somewhere behind SSH. So for the most part,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    88
we'll develop in ``dev-repo``, push to ``test-repo``, test and polish
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    89
there, and push to ``public``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    90
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    91
The key to shared mutable history is to make the target repository, in
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    92
this case ``test-repo``, non-publishing. And, of course, we have to
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
    93
enable the ``evolve`` extension in both ``test-repo`` and ``dev-repo``.
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    94
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    95
First, edit the configuration for ``test-repo``::
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    96
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    97
  $ hg -R test-repo config --edit --local
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    98
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    99
and add ::
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   100
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   101
  [phases]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   102
  publish = false
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   103
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   104
  [extensions]
2865
b0b8cc3064b0 doc: let mercurial find where evolve is installed
Philippe Pepiot <phil@philpep.org>
parents: 2863
diff changeset
   105
  evolve =
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   106
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   107
Then edit the configuration for ``dev-repo``::
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   108
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   109
  $ hg -R dev-repo config --edit --local
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   110
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   111
and add ::
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   112
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   113
  [extensions]
2865
b0b8cc3064b0 doc: let mercurial find where evolve is installed
Philippe Pepiot <phil@philpep.org>
parents: 2863
diff changeset
   114
  evolve =
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   115
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   116
Keep in mind that in real life, these repositories would probably be
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   117
on separate computers, so you'd have to login to each one to configure
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   118
each repository.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   119
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   120
To start things off, let's make one public, immutable changeset::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   121
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   122
  $ cd test-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   123
  $ echo 'my new project' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   124
  $ hg add file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   125
  $ hg commit -m 'create new project'
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   126
  $ hg push
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   127
  [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   128
  added 1 changesets with 1 changes to 1 files
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   129
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   130
and pull that into the development repository::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   131
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   132
  $ cd ../dev-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   133
  $ hg pull -u
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   134
  [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   135
  added 1 changesets with 1 changes to 1 files
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   136
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   137
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   138
Example 1: Amend a shared changeset
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
   139
===================================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   140
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   141
Everything you learned in the `user guide`_ applies to work done in
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   142
``dev-repo``. You can commit, amend, uncommit, evolve, and so forth
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   143
just as before.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   144
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   145
.. _`user guide`: user-guide.html
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   146
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   147
Things get different when you push changesets to ``test-repo``. Or
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   148
rather, things stay the same, which *is* different: because we
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   149
configured ``test-repo`` to be non-publishing, draft changesets stay
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   150
draft when we push them to ``test-repo``. Importantly, they're also
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   151
draft (mutable) in ``test-repo``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   152
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   153
Let's commit a preliminary change and push it to ``test-repo`` for
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   154
testing. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   155
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   156
  $ echo 'fix fix fix' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   157
  $ hg commit -m 'prelim change'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   158
  $ hg push ../test-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   159
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   160
At this point, ``dev-repo`` and ``test-repo`` have the same changesets
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   161
in the same phases:
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   162
4937
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   163
.. figure:: figures/figure-sg01-ab.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   164
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   165
   Figure 1 a: ``dev-repo`` has rev 0:0dc9 public, rev 1:f649 draft
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   166
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   167
.. figure:: figures/figure-sg01-ab.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   168
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   169
   Figure 1 b: the same exact picture in ``test-repo``
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   170
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   171
(You may notice a change in notation from the user guide: now
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   172
changesets are labelled with their revision number and the first four
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   173
digits of the 40-digit hexadecimal changeset ID. Mercurial revision
4934
1765fd925fc1 docs: revision numbers are technically stable
Anton Shestakov <av6@dwimlabs.net>
parents: 4932
diff changeset
   174
numbers are not consistent when working across repositories, especially
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   175
when obsolescence is involved. We'll see why shortly.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   176
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   177
Now let's switch to ``test-repo`` to test our change::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   178
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   179
  $ cd ../test-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   180
  $ hg update
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   181
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   182
Don't forget to ``hg update``! Pushing only adds changesets to a
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   183
remote repository; it does not update the working directory (unless
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   184
you have a hook that updates for you).
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   185
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   186
Now let's imagine the tests failed because we didn't use proper
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   187
punctuation and capitalization (oops). Let's amend our preliminary fix
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   188
(and fix the lame commit message while we're at it)::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   189
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   190
  $ echo 'Fix fix fix' > file1
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   191
  $ hg amend -m 'fix bug 37'
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   192
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   193
For the sake of illustrating how obsolete changesets are not exchanged, let's
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   194
amend again::
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   195
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   196
  $ echo 'Fix fix fix.' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   197
  $ hg amend -m 'fix bug 37'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   198
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   199
Note: some time ago, evolve used to create temporary amend commits. Here,
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   200
amending twice in a row is reminiscent of that behaviour that you may have seen
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   201
in older tutorials.
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   202
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   203
Now we're in a funny intermediate state (figure 2): revision 1:f649 is
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   204
obsolete in ``test-repo``, having been replaced by revision 2:96d8 and then by
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   205
3:522d—but ``dev-repo`` knows nothing of these recent developments.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   206
4937
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   207
.. figure:: figures/figure-sg01-ab.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   208
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   209
   Figure 2 a: ``dev-repo`` same as in Figure 01 a
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   210
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   211
.. figure:: figures/figure-sg02-b.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   212
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   213
   Figure 2 b: ``test-repo`` has rev 0:0dc9 public, revs 1:f649 and 2:96d8
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   214
   obsolete, rev 3:522d draft
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   215
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   216
Let's resynchronize::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   217
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   218
  $ cd ../dev-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   219
  $ hg pull -u
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   220
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   221
  added 1 changesets with 1 changes to 1 files (+1 heads)
4936
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   222
  2 new obsolescence markers
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   223
  obsoleted 1 changesets
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   224
  new changesets 522d503432a2 (1 drafts)
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   225
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
4936
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   226
  updated to "522d503432a2: fix bug 37"
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   227
  1 other heads for branch "default"
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   228
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   229
As seen in figure 3, this transfers the new changeset *and* the
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   230
obsolescence marker for revision 1. However, it does *not* transfer
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   231
2:96d8, because it is hidden. Push and pull transfer obsolescence
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   232
markers between repositories, but they do not transfer hidden changesets.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   233
4937
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   234
.. figure:: figures/figure-sg03.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   235
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   236
   Figure 3: ``dev-repo`` receives rev 2:522d, 1:f649 is now obsolete like in
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   237
   ``test-repo``
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   238
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   239
Because of this deliberately incomplete synchronization, revision
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   240
numbers in ``test-repo`` and ``dev-repo`` are no longer consistent. We
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   241
*must* use changeset IDs.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   242
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   243
Example 2: Amend again, locally
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
   244
===============================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   245
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   246
This process can repeat. Perhaps you figure out a more elegant fix to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   247
the bug, and want to mutate history so nobody ever knows you had a
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   248
less-than-perfect idea. We'll implement it locally in ``dev-repo`` and
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   249
push to ``test-repo``::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   250
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   251
  $ echo 'Fix, fix, and fix' > file1
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   252
  $ hg amend
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   253
  $ echo 'Fix, fix, and fix.' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   254
  $ hg amend
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   255
  $ hg push
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   256
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   257
This time around, the first amend commit stays in ``dev-repo``, and
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   258
it is not transferred to ``test-repo``—the same as before, just in the
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   259
opposite direction. Figure 4 shows the two repositories after amending
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   260
in ``dev-repo`` and pushing to ``test-repo``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   261
4937
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   262
.. figure:: figures/figure-sg04-a.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   263
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   264
   Figure 4 a: in ``dev-repo`` the extra amend commit is 3:e42b
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   265
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   266
.. figure:: figures/figure-sg04-b.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   267
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   268
   Figure 4 b: and in ``test-repo`` it is 2:96d8
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   269
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   270
Let's hop over to ``test-repo`` to test the more elegant fix::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   271
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   272
  $ cd ../test-repo
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   273
  $ hg update
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   274
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   275
1262
eff1acc2511c docs: minor tweaks to sharing guide (suggested by timeless)
Greg Ward <greg@gerg.ca>
parents: 1261
diff changeset
   276
This time, all the tests pass, so no further amending is required.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   277
This bug fix is finished, so we push it to the public repository::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   278
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   279
  $ hg push
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   280
  [...]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   281
  added 1 changesets with 1 changes to 1 files
4936
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   282
  4 new obsolescence markers
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   283
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   284
Note that only one changeset—the final version, after all the
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   285
amendments—was actually pushed. Again, Mercurial doesn't transfer
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   286
hidden changesets on push and pull.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   287
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   288
.. _`concept guide`: concepts.html
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   289
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   290
So the picture in ``public`` is much simpler than in either
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   291
``dev-repo`` or ``test-repo``. Neither of our missteps nor our amendments
1262
eff1acc2511c docs: minor tweaks to sharing guide (suggested by timeless)
Greg Ward <greg@gerg.ca>
parents: 1261
diff changeset
   292
are publicly visible, just the final, beautifully polished changeset:
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   293
4937
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   294
.. figure:: figures/figure-sg05.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   295
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   296
   Figure 5: in ``public`` repo with revs 0:0dc9 and 1:7b49, both public
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   297
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   298
There is one important step left to do. Because we pushed from
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   299
``test-repo`` to ``public``, the pushed changeset is in *public* phase
1263
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   300
in those two repositories. But ``dev-repo`` has been out-of-the-loop;
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   301
changeset 7b49 is still *draft* there. If we're not careful, we might
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   302
mutate history in ``dev-repo``, obsoleting a changeset that is already
1263
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   303
public. Let's avoid that situation for now by pushing up to
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   304
``dev-repo``::
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   305
1263
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   306
  $ hg push ../dev-repo
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   307
  pushing to ../dev-repo
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   308
  searching for changes
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   309
  no changes found
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   310
1263
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   311
Even though no *changesets* were pushed, Mercurial still pushed
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   312
obsolescence markers and phase changes to ``dev-repo``.
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   313
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   314
A final note: since this fix is now *public*, it is immutable. It's no
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   315
longer possible to amend it::
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   316
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   317
  $ hg amend -m 'fix bug 37'
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   318
  abort: cannot amend public changesets
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   319
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   320
This is, after all, the whole point of Mercurial's phases: to prevent
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   321
rewriting history that has already been published.
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   322
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   323
Sharing with multiple developers: code review
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   324
---------------------------------------------
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   325
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   326
Now that you know how to share your own mutable history across
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   327
multiple computers, you might be wondering if it makes sense to share
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   328
mutable history with others. It does, but you have to be careful, stay
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   329
alert, and *communicate* with your peers.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   330
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   331
Code review is a good use case for sharing mutable history across
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   332
multiple developers: Alice commits a draft changeset, submits it for
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   333
review, and amends her changeset until her reviewer is satisfied.
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   334
Meanwhile, Bob is also committing draft changesets for review,
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   335
amending until his reviewer is satisfied. Once a particular changeset
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   336
passes review, the respective author (Alice or Bob) pushes it to the
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   337
public (publishing) repository.
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   338
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   339
Incidentally, the reviewers here can be anyone: maybe Bob and Alice
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   340
review each other's work; maybe the same third party reviews both; or
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   341
maybe they pick different experts to review their work on different
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   342
parts of a large codebase. Similarly, it doesn't matter if reviews are
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   343
conducted in person, by email, or by carrier pigeon. Code review is
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   344
outside of the scope of Mercurial, so all we're looking at here
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   345
is the mechanics of committing, amending, pushing, and pulling.
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   346
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   347
Setting up
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   348
==========
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   349
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   350
To demonstrate, let's start with the ``public`` repository as we left
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   351
it in the last example, with two immutable changesets (figure 5
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   352
above). We'll clone a ``review`` repository from it, and then Alice
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   353
and Bob will both clone from ``review``. ::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   354
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   355
  $ hg clone public review
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   356
  updating to branch default
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   357
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   358
  $ hg clone review alice
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   359
  updating to branch default
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   360
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   361
  $ hg clone review bob
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   362
  updating to branch default
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   363
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   364
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   365
We need to configure Alice's and Bob's working repositories to enable
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   366
``evolve``. First, edit Alice's configuration with ::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   367
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   368
  $ hg -R alice config --edit --local
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   369
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   370
and add ::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   371
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   372
  [extensions]
2865
b0b8cc3064b0 doc: let mercurial find where evolve is installed
Philippe Pepiot <phil@philpep.org>
parents: 2863
diff changeset
   373
  evolve =
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   374
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   375
Then edit Bob's repository configuration::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   376
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   377
  $ hg -R bob config --edit --local
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   378
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   379
and add the same text.
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   380
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   381
Example 3: Alice commits and amends a draft fix
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   382
===============================================
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   383
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   384
We'll follow Alice working on a bug fix. We're going to use bookmarks to
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   385
make it easier to understand multiple branch heads in the ``review``
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   386
repository, so Alice starts off by creating a bookmark and committing
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   387
her first attempt at a fix::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   388
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   389
  $ hg bookmark bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   390
  $ echo 'fix' > file2
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   391
  $ hg commit -A -u alice -m 'fix bug 15 (v1)'
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   392
  adding file2
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   393
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   394
Note the unorthodox "(v1)" in the commit message. We're just using
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   395
that to make this tutorial easier to follow; it's not something we'd
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   396
recommend in real life.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   397
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   398
Of course Alice wouldn't commit unless her fix worked to her
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   399
satisfaction, so it must be time to solicit a code review. She does
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   400
this by pushing to the ``review`` repository::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   401
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   402
  $ hg push -B bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   403
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   404
  added 1 changesets with 1 changes to 1 files
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   405
  exporting bookmark bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   406
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   407
(The use of ``-B`` is important to ensure that we only push the
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   408
bookmarked head, and that the bookmark itself is pushed. See this
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   409
`guide to bookmarks`_, especially the `Sharing Bookmarks`_ section, if
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   410
you're not familiar with bookmarks.)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   411
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   412
.. _`guide to bookmarks`: http://mercurial.aragost.com/kick-start/en/bookmarks/
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   413
.. _`Sharing Bookmarks`: http://mercurial.aragost.com/kick-start/en/bookmarks/#sharing-bookmarks
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   414
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   415
Some time passes, and Alice receives her code review. As a result,
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   416
Alice revises her fix and submits it for a second review::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   417
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   418
  $ echo 'Fix.' > file2
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   419
  $ hg amend -m 'fix bug 15 (v2)'
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   420
  $ hg push
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   421
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   422
  added 1 changesets with 1 changes to 1 files (+1 heads)
4936
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   423
  1 new obsolescence markers
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   424
  obsoleted 1 changesets
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   425
  updating bookmark bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   426
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   427
Figure 6 shows the state of the ``review`` repository at this point.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   428
4937
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   429
.. figure:: figures/figure-sg06.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   430
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   431
   Figure 6: rev 2:4e96 is Alice's obsolete v1, rev 3:3363 is her v2; both
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   432
   children of rev 1:7b49
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   433
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   434
After a busy morning of bug fixing, Alice stops for lunch. Let's see
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   435
what Bob has been up to.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   436
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   437
Example 4: Bob implements and publishes a new feature
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   438
=====================================================
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   439
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   440
Meanwhile, Bob has been working on a new feature. Like Alice, he'll
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   441
use a bookmark to track his work, and he'll push that bookmark to the
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   442
``review`` repository, so that reviewers know which changesets to
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   443
review. ::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   444
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   445
  $ cd ../bob
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   446
  $ echo 'stuff' > file1
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   447
  $ hg bookmark featureX
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   448
  $ hg commit -u bob -m 'implement feature X (v1)'          # rev 4:c7ff
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   449
  $ hg push -B featureX
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   450
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   451
  added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   452
  exporting bookmark featureX
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   453
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   454
When Bob receives his code review, he improves his implementation a
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   455
bit, amends, and submits the resulting changeset for review::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   456
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   457
  $ echo 'do stuff' > file1
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   458
  $ hg amend -m 'implement feature X (v2)'                  # rev 5:1bb4
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   459
  $ hg push
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   460
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   461
  added 1 changesets with 1 changes to 1 files (+1 heads)
4936
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   462
  1 new obsolescence markers
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   463
  obsoleted 1 changesets
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   464
  updating bookmark featureX
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   465
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   466
Unfortunately, that still doesn't pass muster. Bob's reviewer insists
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   467
on proper capitalization and punctuation. ::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   468
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   469
  $ echo 'Do stuff.' > file1
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   470
  $ hg amend -m 'implement feature X (v3)'                  # rev 6:9d21
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   471
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   472
On the bright side, the second review said, "Go ahead and publish once
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   473
you fix that." So Bob immediately publishes his third attempt::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   474
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   475
  $ hg push ../public
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   476
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   477
  added 1 changesets with 1 changes to 1 files
4936
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   478
  2 new obsolescence markers
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   479
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   480
It's not enough just to update ``public``, though! Other people also
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   481
use the ``review`` repository, and right now it doesn't have Bob's
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   482
latest amendment ("v3", revision 6:9d21), nor does it know that the
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   483
predecessor of that changeset ("v2", revision 5:1bb4) is obsolete. Thus,
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   484
Bob pushes to ``review`` as well::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   485
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   486
  $ hg push ../review
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   487
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   488
  added 1 changesets with 1 changes to 1 files (+1 heads)
4936
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   489
  1 new obsolescence markers
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   490
  obsoleted 1 changesets
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   491
  updating bookmark featureX
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   492
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   493
Figure 7 shows the result of Bob's work in both ``review`` and
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   494
``public``.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   495
4937
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   496
.. figure:: figures/figure-sg07-a.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   497
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   498
   Figure 7 a: ``review`` includes Alice's draft work on bug 15, as well as
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   499
   Bob's v1, v2, and v3 changes for feature X: v1 and v2 obsolete, v3 public
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   500
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   501
.. figure:: figures/figure-sg07-b.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   502
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   503
   Figure 7 b: ``public`` contains only the final, public implementation of
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   504
   feature X
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   505
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   506
Incidentally, it's important that Bob push to ``public`` *before*
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   507
``review``. If he pushed to ``review`` first, then revision 6:540b
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   508
would still be in *draft* phase in ``review``, but it would be
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   509
*public* in both Bob's local repository and the ``public`` repository.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   510
That could lead to confusion at some point, which is easily avoided by
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   511
pushing first to ``public``.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   512
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   513
Example 5: Alice integrates and publishes
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   514
=========================================
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   515
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   516
Finally, Alice gets back from lunch and sees that the carrier pigeon
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   517
with her second review has arrived (or maybe it's in her email inbox).
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   518
Alice's reviewer approved her amended changeset, so she pushes it to
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   519
``public``::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   520
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   521
  $ hg push ../public
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   522
  [...]
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   523
  remote has heads on branch 'default' that are not known locally: 9d21d673314a
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   524
  abort: push creates new remote head 3363442626b3 with bookmark 'bug15'!
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   525
  (pull and merge or see 'hg help push' for details about pushing new heads)
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   526
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   527
Oops! Bob has won the race to push first to ``public``. So Alice needs
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   528
to integrate with Bob: let's pull his changeset(s) and see what the
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   529
branch heads are. ::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   530
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   531
  $ hg pull ../public
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   532
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   533
  added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   534
  (run 'hg heads' to see heads, 'hg merge' to merge)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   535
  $ hg log -G -q -r 'head()' --template '{rev}:{node|short}  ({author})\n'
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   536
  o  4:9d21d673314a  (bob)
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   537
  |
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   538
  | @  3:3363442626b3  (alice)
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   539
  |/
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   540
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   541
We'll assume Alice and Bob are perfectly comfortable with rebasing
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   542
changesets. (After all, they're already using mutable history in the
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   543
form of ``amend``.) So Alice rebases her changeset on top of Bob's and
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   544
publishes the result::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   545
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   546
  $ hg rebase -d 4
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   547
  $ hg push ../public
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   548
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   549
  added 1 changesets with 1 changes to 1 files
4936
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   550
  2 new obsolescence markers
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   551
  $ hg push ../review
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   552
  [...]
4936
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   553
  added 1 changesets with 0 changes to 1 files
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   554
  1 new obsolescence markers
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   555
  obsoleted 1 changesets
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   556
  updating bookmark bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   557
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   558
The result, in both ``review`` and ``public`` repositories, is shown
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   559
in figure 8.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   560
4937
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   561
.. figure:: figures/figure-sg08-a.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   562
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   563
   Figure 8 a: ``review`` shows v1 and v2 of Alice's fix, then v1, v2, v3 of
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   564
   Bob's feature, finally Alice's fix rebased onto Bob's
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   565
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   566
.. figure:: figures/figure-sg08-b.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   567
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   568
   Figure 8 b: ``public`` just shows the final public version of each changeset
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   569
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   570
Getting into trouble with shared mutable history
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   571
------------------------------------------------
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   572
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   573
Mercurial with ``evolve`` is a powerful tool, and using powerful tools
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   574
can have consequences. (You can cut yourself badly with a sharp knife,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   575
but every competent chef keeps several around. Ever try to chop onions
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   576
with a spoon?)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   577
4618
803d32f4e498 docs: change `unstable` references to `orphan`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4617
diff changeset
   578
In the user guide, we saw examples of *orphan* changesets, which are
4619
93514c421528 docs: change `troubled` references to `unstable`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4618
diff changeset
   579
the most common type of unstable changeset. (Recall that a
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   580
non-obsolete changeset with obsolete ancestors is an orphan.)
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   581
4620
a05bfdf372fb docs: change `divergent` references to `content-divergent`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4619
diff changeset
   582
Two other types of instability can happen: *content-divergent* and
4621
8784dfc6537c docs: change `bumped` references to `phase-divergent`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4620
diff changeset
   583
*phase-divergent* changesets. Both are more likely with shared mutable
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   584
history, especially mutable history shared by multiple developers.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   585
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   586
Setting up
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   587
==========
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   588
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   589
For these examples, we're going to use a slightly different workflow:
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   590
as before, Alice and Bob share a ``public`` repository. But this time
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   591
there is no ``review`` repository. Instead, Alice and Bob put on their
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   592
cowboy hats, throw good practice to the wind, and pull directly from
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   593
each other's working repositories.
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   594
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   595
So we throw away everything except ``public`` and reclone::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   596
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   597
  $ rm -rf review alice bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   598
  $ hg clone public alice
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   599
  updating to branch default
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   600
  2 files updated, 0 files merged, 0 files removed, 0 files unresolved
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   601
  $ hg clone public bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   602
  updating to branch default
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   603
  2 files updated, 0 files merged, 0 files removed, 0 files unresolved
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   604
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   605
Once again we have to configure their repositories: enable ``evolve``
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   606
and (since Alice and Bob will be pulling directly from each other)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   607
make their repositories non-publishing. Edit Alice's configuration::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   608
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   609
  $ hg -R alice config --edit --local
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   610
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   611
and add ::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   612
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   613
  [extensions]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   614
  rebase =
2865
b0b8cc3064b0 doc: let mercurial find where evolve is installed
Philippe Pepiot <phil@philpep.org>
parents: 2863
diff changeset
   615
  evolve =
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   616
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   617
  [phases]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   618
  publish = false
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   619
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   620
Then edit Bob's repository configuration::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   621
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   622
  $ hg -R bob config --edit --local
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   623
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   624
and add the same text.
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   625
4620
a05bfdf372fb docs: change `divergent` references to `content-divergent`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4619
diff changeset
   626
Example 6: Content-divergent changesets
a05bfdf372fb docs: change `divergent` references to `content-divergent`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4619
diff changeset
   627
=======================================
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   628
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   629
When an obsolete changeset has two successors, those successors are
4620
a05bfdf372fb docs: change `divergent` references to `content-divergent`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4619
diff changeset
   630
*content-divergent*. One way to get into such a situation is by failing
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   631
to communicate with your teammates. Let's see how that might happen.
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   632
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   633
First, we'll have Bob commit a bug fix that could still be improved::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   634
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   635
  $ cd bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   636
  $ echo 'pretty good fix' >> file1
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   637
  $ hg commit -u bob -m 'fix bug 24 (v1)'                   # rev 4:b2be
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   638
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   639
Since Alice and Bob are now in cowboy mode, Alice pulls Bob's draft
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   640
changeset and amends it herself. ::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   641
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   642
  $ cd ../alice
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   643
  $ hg pull -u ../bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   644
  [...]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   645
  added 1 changesets with 1 changes to 1 files
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   646
  $ echo 'better fix (alice)' >> file1
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   647
  $ hg amend -u alice -m 'fix bug 24 (v2 by alice)'
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   648
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   649
But Bob has no idea that Alice just did this. (See how important good
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   650
communication is?) So he implements a better fix of his own::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   651
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   652
  $ cd ../bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   653
  $ echo 'better fix (bob)' >> file1
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   654
  $ hg amend -u bob -m 'fix bug 24 (v2 by bob)'             # rev 5:541f
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   655
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   656
At this point, the divergence exists, but only in theory: Bob's
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   657
original changeset, 4:b2be, is obsolete and has two successors. But
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   658
those successors are in different repositories, so the trouble is not
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   659
visible to anyone yet. It will be as soon as Bob pulls from Alice's
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   660
repository (or vice-versa). ::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   661
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   662
  $ hg pull ../alice
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   663
  [...]
4936
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   664
  added 1 changesets with 1 changes to 1 files (+1 heads)
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   665
  1 new obsolescence markers
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   666
  2 new content-divergent changesets
deec516b6e34 docs: add some up-to-date output from push/pull commands
Anton Shestakov <av6@dwimlabs.net>
parents: 4935
diff changeset
   667
  new changesets e3a586fd2377 (1 drafts)
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   668
  (run 'hg heads' to see heads, 'hg merge' to merge)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   669
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   670
Figure 9 shows the situation in Bob's repository.
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   671
4937
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   672
.. figure:: figures/figure-sg09.svg
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   673
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   674
   Figure 9: Bob's repo with 2 heads for the 2 content-divergent changesets,
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   675
   5:541f and 6:e3a5; wc is at 5:541f; both are successors of obsolete 4:b2be,
0d1893c1044c docs: add SVG figures for sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4936
diff changeset
   676
   hence divergence
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   677
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   678
Now we need to get out of trouble. As usual, the answer is to evolve
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   679
history. ::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   680
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   681
  $ HGMERGE=internal:other hg evolve
4935
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   682
  merge:[5] fix bug 24 (v2 by bob)
3874bc10d4a7 docs: add two more amend commits to simulate temporary amend commits
Anton Shestakov <av6@dwimlabs.net>
parents: 4934
diff changeset
   683
  with: [6] fix bug 24 (v2 by alice)
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   684
  base: [4] fix bug 24 (v1)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   685
  0 files updated, 1 files merged, 0 files removed, 0 files unresolved
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   686
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   687
Figure 10 shows how Bob's repository looks now.
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   688
4973
f3faafa1e064 docs: add missing Figure 10 to sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4937
diff changeset
   689
.. figure:: figures/figure-sg10.svg
f3faafa1e064 docs: add missing Figure 10 to sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4937
diff changeset
   690
f3faafa1e064 docs: add missing Figure 10 to sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4937
diff changeset
   691
  Figure 10: only one visible head, 7:aa82, successor to hidden 5:541f and
f3faafa1e064 docs: add missing Figure 10 to sharing.rst
Anton Shestakov <av6@dwimlabs.net>
parents: 4937
diff changeset
   692
  6:e3a5
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   693
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   694
We carefully dodged a merge conflict by specifying a merge tool
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   695
(``internal:other``) that will take Alice's changes over Bob's. (You
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   696
might wonder why Bob wouldn't prefer his own changes by using
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   697
``internal:local``. He's avoiding a `bug`_ in ``evolve`` that occurs
4620
a05bfdf372fb docs: change `divergent` references to `content-divergent`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4619
diff changeset
   698
when evolving content-divergent changesets using ``internal:local``.)
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   699
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   700
# XXX this link does not work
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   701
.. _`bug`: https://bitbucket.org/marmoute/mutable-history/issue/48/
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   702
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   703
** STOP HERE: WORK IN PROGRESS **
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   704
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   705
Phase-divergence: when a rewritten changeset is made public
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   706
===========================================================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   707
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   708
If Alice and Bob are collaborating on some mutable
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   709
changesets, it's possible to get into a situation where an otherwise
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   710
worthwhile changeset cannot be pushed to the public repository; it is
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   711
*phase-divergent* with another changeset that was made public first.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   712
Let's demonstrate one way this could happen.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   713
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   714
It starts with Alice committing a bug fix. Right now, we don't yet
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   715
know if this bug fix is good enough to push to the public repository,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   716
but it's good enough for Alice to commit. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   717
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   718
  $ cd alice
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   719
  $ echo 'fix' > file2
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   720
  $ hg commit -A -m 'fix bug 15'
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   721
  adding file2
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   722
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   723
Now Bob has a bad idea: he decides to pull whatever Alice is working
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   724
on and tweak her bug fix to his taste::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   725
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   726
  $ cd ../bob
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   727
  $ hg pull -u ../alice
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   728
  [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   729
  added 1 changesets with 1 changes to 1 files
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   730
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   731
  $ echo 'Fix.' > file2
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   732
  $ hg amend -A -m 'fix bug 15 (amended)'
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   733
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   734
(Note the lack of communication between Alice and Bob. Failing to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   735
communicate with your colleagues is a good way to get into trouble.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   736
Nevertheless, ``evolve`` can usually sort things out, as we will see.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   737
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   738
  [figure SG06: Bob's repo with one amendment]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   739
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   740
After some testing, Alice realizes her bug fix is just fine as it is:
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   741
no need for further polishing and amending, this changeset is ready to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   742
publish. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   743
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   744
  $ cd ../alice
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   745
  $ hg push
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   746
  [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   747
  added 1 changesets with 1 changes to 1 files
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   748
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   749
This introduces a contradiction: in Bob's repository, changeset 2:e011
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   750
(his copy of Alice's fix) is obsolete, since Bob amended it. But in
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   751
Alice's repository (and the ``public`` repository), that changeset is
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   752
public: it is immutable, carved in stone for all eternity. No changeset
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   753
can be both obsolete and public, so Bob is in for a surprise the next
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   754
time he pulls from ``public``::
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   755
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   756
  $ cd ../bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   757
  $ hg pull -q -u
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   758
  1 new phase-divergent changesets
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   759
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   760
Figure 7 shows what just happened to Bob's repository: changeset
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   761
2:e011 is now public, so it can't be obsolete. When that changeset was
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   762
obsolete, it made perfect sense for it to have a successor, namely
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   763
Bob's amendment of Alice's fix (changeset 4:fe88). But it's illogical
4619
93514c421528 docs: change `troubled` references to `unstable`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4618
diff changeset
   764
for a public changeset to have a successor, so 4:fe88 is unstable:
4621
8784dfc6537c docs: change `bumped` references to `phase-divergent`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4620
diff changeset
   765
it has become *phase-divergent*.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   766
4621
8784dfc6537c docs: change `bumped` references to `phase-divergent`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4620
diff changeset
   767
  [figure SG07: 2:e011 now public not obsolete, 4:fe88 now phase-divergent]
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   768
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   769
As usual when there's trouble in your repository, the solution is to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   770
evolve it::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   771
4920
d1066fb2c95a docs: remove --all from hg evolve, since it's been the default for some time
Anton Shestakov <av6@dwimlabs.net>
parents: 4621
diff changeset
   772
  $ hg evolve
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   773
4621
8784dfc6537c docs: change `bumped` references to `phase-divergent`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4620
diff changeset
   774
Figure 8 illustrates Bob's repository after evolving away the phase-divergent
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   775
changeset. Ignoring the obsolete changesets, Bob now has a nice,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   776
clean, simple history. His amendment of Alice's bug fix lives on, as
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   777
changeset 5:227d—albeit with a software-generated commit message. (Bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   778
should probably amend that changeset to improve the commit message.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   779
But the important thing is that his repository no longer has any
4619
93514c421528 docs: change `troubled` references to `unstable`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4618
diff changeset
   780
unstable changesets, thanks to ``evolve``.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   781
4621
8784dfc6537c docs: change `bumped` references to `phase-divergent`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4620
diff changeset
   782
  [figure SG08: 5:227d is new, formerly phase-divergent changeset 4:fe88 now hidden]
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   783
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   784
Conclusion
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   785
----------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   786
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   787
Mutable history is a powerful tool. Like a sharp knife, an experienced
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   788
user can do wonderful things with it, much more wonderful than with a
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   789
dull knife (never mind a rusty spoon). At the same time, an
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   790
inattentive or careless user can do harm to himself or others.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   791
Mercurial with ``evolve`` goes to great lengths to limit the harm you
4619
93514c421528 docs: change `troubled` references to `unstable`
Matt Harbison <matt_harbison@yahoo.com>
parents: 4618
diff changeset
   792
can do by trying to handle all possible types of “unstable”
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   793
changesets. Nevertheless, having a first-aid kit nearby does not mean
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
   794
you should stop being careful with sharp knives.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   795
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   796
Mutable history shared across multiple repositories by a single
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   797
developer is a natural extension of this model. Once you are used to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   798
using a single sharp knife on its own, it's pretty straightforward to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   799
chop onions and mushrooms using the same knife, or to alternate
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   800
between two chopping boards with different knives.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   801
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   802
Mutable history shared by multiple developers is a scary place to go.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   803
Imagine a professional kitchen full of expert chefs tossing their
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   804
favourite knives back and forth, with the occasional axe or chainsaw
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   805
thrown in to spice things up. If you're confident that you *and your
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   806
colleagues* can do it without losing a limb, go for it. But be sure to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   807
practice a lot first before you rely on it!