tests/test-newbranch.out

named branches: server branchmap wire protocol support (issue736)

The repository command, 'branchmap', returns a dictionary, branchname
-> [branchheads], and will be implemented for localrepo, httprepo and
sshrepo.

The following wire format is used for returning data:

branchname1 branch1head2 branch1head2 ...
branchname2 ...
...

Branch names are URL encoded to escape white space, and branch heads
are sent as hex encoded node ids. All branches and all their heads are
sent.

The background and motivation for this command is the desire for a
richer named branch semantics when pushing changesets. The details are
explained in the original proposal which is included below.


1. BACKGROUND

The algorithm currently implemented in Mercurial only considers the
graph theoretical heads when determining whether new heads are
created, rather than using the branch heads as a count (the algorithm
considers a branch head effectively closed when it is merged into
another branch or a new named branch is started from that point
onward).

Our particular problem with the algorithm is that we'd like to see the
following case working without forcing a push:

Upsteam has:

(0:dev) ---- (1:dev)
\
 `--- (2:stable)

Someone merges stable into dev:

(0:dev) ---- (1:dev) ------(3:dev)
\                         /
 `--- (2:stable) --------´

This can be pushed without --force (as it should).
Now someone else does some coding on stable (a bug fix, say):

(0:dev) ---- (1:dev) ------(3:dev)
\                          /
 `--- (2:stable) ---------´---------(4:stable)

This time we need --force to push.

We allow this to be pushed without using --force by getting all the
remote branch heads (by extending the wire protocol with a new
function).

We would, furthermore, also prefer if it is impossible to push a new
branch without --force (or a later --newbranch option so --force isn't
shoe-horned into too many disparate functions, if need be), except of
course in the case where the remote repository is empty.

This is what our patches accomplish.


2. ALTERNATIVES

We have, of course, considered some alternatives to reconstructing
enough information to decide whether we are creating new remote branch
heads, before we added the new wire protocol command.

2.1. LOOKUP ON REMOTE

The main alternative is to use the information from remote.heads() and
remote.lookup() to try to reconstruct enough graph information to
decide whether we are creating new heads. This is not adequate as
illustrated below.

Remember that each lookup is typically a request-response pair over
SSH or HTTP(S).

If we have a simple repository at the remote end like this:

(0:dev) ---- (1:dev) ---- (3:stable)
\
 `--- (2:dev)

then remote.heads() will yield [2, 3]. Assume we have nodes [0, 1, 2]
locally and want to create a new node, 4:dev, as a descendant from
(1:dev), which should be OK as 1:dev is a branch head.

If we do remote.lookup('dev') we will get [2]. Thus, we can get
information about whether a branch exists on the remote server or not,
but this does not solve our problem of figuring out whether we are
creating new heads or not.

Pushing 4:dev ought to be OK, since after the push, we still only have
two heads on branch a.

Using remote.lookup() and remote.heads() is thus not adequate to
consistently decide whether we are creating new remote heads (e.g. in
this situation the latter would never return 1:dev).

2.2. USING INCOMING TO RECONSTRUCT THE GRAPH

An alternative would be to use information equivalent to hg incoming
to get the full remote graph in addition to the local graph.

To do this, we would have to get a changegroup(subset) bundle
representing the remote end (which may be a substantial amount of
data), getting the branch heads from an instantiated bundlerepository,
deleting the bundle, and finally, we can compute the prepush logic.

While this is backwards compatible, it will cause a possibly
substantial slowdown of the push command as it first needs to pull in
all changes.


3. FURTHER ARGUMENTS IN FAVOUR OF THE BRANCHMAP WIRE-PROTOCOL EXTENSION

Currently, the commands incoming and pull, work based on the tip of a
given branch if used with "-r branchname", making it hard to get all
revisions of a certain branch only (if it has multiple heads). This
can be solved by requesting the remote's branchheads and letting the
revisions to be used with the command be these heads. This can be done
by extending the commands with a new option, e.g.:

hg pull -b branchname

which will be turned into the equivalent of:

hg pull -r branchhead1 -r branchhead2 -r branchhead3

We have a simple follow-up patch that can do this ready as well
(although not submitted yet as it is pending the acceptance of the
branch patch).


4. WRAP-UP

We generally find that the branchmap wire protocol extension can
provide better named branch support to Mercurial. Currently, some
things, like the initial push scenario in this mail, are fairly
counter-intuitive, and the more often you have to force push, the more
it is likely you will get a lot of spurious and unnecessary merge
nodes. Also, restricting incoming and pull to all changes on a branch
rather than changes on the tip-most head would be a sensible extension
to making named branches a first class citizen in Mercurial.
Currently, named branches sometimes feel like a late-coming unwanted
step-child.

We have run it in a production environment for a while, with fewer
multiple heads occurring in our repositories and fewer confused users
as a result.

Also, it fixes the long-standing issue 736.

Co-contributor: Sune Foldager <[e-mail]>

marked working directory as branch foo
foo
marked working directory as branch bar
% branch shadowing
abort: a branch of the same name already exists (use --force to override)
marked working directory as branch default
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
foo
created new head
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)
foo
changeset:   5:5f8fb06e083e
branch:      foo
tag:         tip
parent:      4:4909a3732169
parent:      3:bf1bc2f45e83
user:        test
date:        Mon Jan 12 13:46:40 1970 +0000
summary:     merge

changeset:   4:4909a3732169
branch:      foo
parent:      1:b699b1cec9c2
user:        test
date:        Mon Jan 12 13:46:40 1970 +0000
summary:     modify a branch

changeset:   3:bf1bc2f45e83
user:        test
date:        Mon Jan 12 13:46:40 1970 +0000
summary:     clear branch name

changeset:   2:67ec16bde7f1
branch:      bar
user:        test
date:        Mon Jan 12 13:46:40 1970 +0000
summary:     change branch name

changeset:   1:b699b1cec9c2
branch:      foo
user:        test
date:        Mon Jan 12 13:46:40 1970 +0000
summary:     add branch name

changeset:   0:be8523e69bf8
user:        test
date:        Mon Jan 12 13:46:40 1970 +0000
summary:     initial

foo                            5:5f8fb06e083e
default                        3:bf1bc2f45e83 (inactive)
bar                            2:67ec16bde7f1 (inactive)
foo
default
bar
% test for invalid branch cache
rolling back last transaction
changeset:   4:4909a3732169
branch:      foo
tag:         tip
parent:      1:b699b1cec9c2
user:        test
date:        Mon Jan 12 13:46:40 1970 +0000
summary:     modify a branch

invalidating branch cache (tip differs)
changeset:   4:4909a3732169c0c20011c4f4b8fdff4e3d89b23f
branch:      foo
tag:         tip
parent:      1:b699b1cec9c2966b3700de4fef0dc123cd754c31
parent:      -1:0000000000000000000000000000000000000000
manifest:    4:d01b250baaa05909152f7ae07d7a649deea0df9a
user:        test
date:        Mon Jan 12 13:46:40 1970 +0000
files:       a
extra:       branch=foo
description:
modify a branch


4:4909a3732169
4909a3732169c0c20011c4f4b8fdff4e3d89b23f 4
be8523e69bf892e25817fc97187516b3c0804ae4 default
bf1bc2f45e834c75404d0ddab57d53beab56e2f8 default
4909a3732169c0c20011c4f4b8fdff4e3d89b23f foo
67ec16bde7f1575d523313b9bca000f6a6f12dca bar
% push should update the branch cache
% pushing just rev 0
be8523e69bf892e25817fc97187516b3c0804ae4 0
be8523e69bf892e25817fc97187516b3c0804ae4 default
% pushing everything
4909a3732169c0c20011c4f4b8fdff4e3d89b23f 4
be8523e69bf892e25817fc97187516b3c0804ae4 default
bf1bc2f45e834c75404d0ddab57d53beab56e2f8 default
4909a3732169c0c20011c4f4b8fdff4e3d89b23f foo
67ec16bde7f1575d523313b9bca000f6a6f12dca bar
% update with no arguments: tipmost revision of the current branch
bf1bc2f45e83
4909a3732169 (foo) tip
marked working directory as branch foobar
abort: branch foobar not found
% fastforward merge
marked working directory as branch ff
adding ff
0 files updated, 0 files merged, 1 files removed, 0 files unresolved
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)
foo
changeset:   6:f0c74f92a385
branch:      foo
tag:         tip
parent:      4:4909a3732169
parent:      5:c420d2121b71
user:        test
date:        Mon Jan 12 13:46:40 1970 +0000
summary:     Merge ff into foo

a
ff
% test merging, add 3 default heads and one test head
adding a
adding b
0 files updated, 0 files merged, 1 files removed, 0 files unresolved
adding c
created new head
0 files updated, 0 files merged, 1 files removed, 0 files unresolved
adding d
created new head
0 files updated, 0 files merged, 1 files removed, 0 files unresolved
marked working directory as branch test
adding e
created new head
changeset:   4:3a1e01ed1df4
branch:      test
tag:         tip
parent:      0:cb9a9f314b8b
user:        test
date:        Thu Jan 01 00:00:00 1970 +0000
summary:     e

changeset:   3:980f7dc84c29
parent:      0:cb9a9f314b8b
user:        test
date:        Thu Jan 01 00:00:00 1970 +0000
summary:     d

changeset:   2:d36c0562f908
parent:      0:cb9a9f314b8b
user:        test
date:        Thu Jan 01 00:00:00 1970 +0000
summary:     c

changeset:   1:d2ae7f538514
user:        test
date:        Thu Jan 01 00:00:00 1970 +0000
summary:     b

changeset:   0:cb9a9f314b8b
user:        test
date:        Thu Jan 01 00:00:00 1970 +0000
summary:     a

% implicit merge with test branch as parent
abort: branch 'test' has one head - please merge with an explicit rev
1 files updated, 0 files merged, 1 files removed, 0 files unresolved
% implicit merge with default branch as parent
abort: branch 'default' has 3 heads - please merge with an explicit rev
% 3 branch heads, explicit merge required
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)
% 2 branch heads, implicit merge works
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)