@need 3200

@node Idempotent Merging
@chapter Idempotent Merging

[Idempotent merging is not implemented in the current release.]


Let's suppose that we have a main development path, with several
branches:

@example
@group
        main
        ----
        base-0
        patch-1
        patch-2-----------------------> branch-a
@end group
@group
        patch-3                 |
@end group
@group
        patch-4                 |
        patch-5                 |-----> branch-b
                                |
                                |
                                 -----> branch-c
@end group
@group
@end group
@end example

What happens if each of the three branches checks in a revision that
is an @code{update} against the @code{main} branch.  In other words, each branch
will have a delta that that summarizes patches @code{3..5} of the main
branch.


If we try to @code{replay} from two or more of those branches, we'll wind
up replaying several of those deltas that summarize @code{3..5}.  Those
patches will be redundant and will likely generate merge conflicts.


@code{Update} won't do much better in this case.  The common ancestor of
all three branches is their @code{base-0} revision, which is the same as
@code{patch-2} on @code{main}.


Now suppose I start with the latest revision on @code{branch-a}, which
includes patches @code{3..5} of the main branch, plus some changes specific
to @code{branch-a}.  And @code{branch-b} is similar -- it has @code{3..5} from @code{main}
some changes specific to @code{branch-b}.


If I @code{update} my @code{branch-A} revision against @code{branch-B}, the @code{A}
revision is compared to the common ancestor.  In essence:

@example
@group
        upate_patch = delta (branch-a--latest, main--patch-2)
@end group
@group
@end group
@end example

Note that the update patch contains all the changes needed for @code{3..5}
from @code{main}. @code{update} will apply that patch to the latest revision of
@code{branch-B}:

@example
@group
        update_a_from_b = update_patch [ branch-b--latest ]
@end group
@group
@end group
@end example

@noindent
but @code{branch-b--latest} already includes patches @code{3..5} from main.
There's a good chance the merge will have conflicts.


When such messes occur, the @code{reconcile} command, introduced in the
previous chapter, can help you out of them.  But wouldn't it be better
to avoid such problems in the first place?

@need 3200

@section The i-merge Command

A tool for tackling the problem directly is an @code{idempotent} merge:

@example
@group
        % larch i-merge [  --update [ARCHIVE/]REVISION
                        | --replay [ARCHIVE/]REVISION ]
                       [ARCHIVE/]SOURCE-REVISION
                       directory
@end group
@group
@end group
@end example

That creates a project tree in DIRECTORY by using @code{larch get} to obtain
the @code{SOURCE-REVISION}, then applying each of the specified @code{update}
and @code{replay} commands, in the order specified.


If any merge conflicts occur, the command issues an error, and leaves
the partially meged directory, along with an explanation of where it
left off.


If the command succeeds, though, the project tree will be left in a
special state which permits the use of the @code{--idempotent} flag to
@code{commit}.

@example
@group
        % larch commit --idempontent
@end group
@group
@end group
@end example

@noindent
which, in fact, creates two new revisions.  The first revision created
is the intermediate directory, containing only @code{SOURCE-REVISION} plus
the series of @code{updates} and @code{replays} you specified -- no other
changes.  The log message for this revision is automatically
generated, and has the special header @code{idempotent-merge:} with the
list of patches applied.


The second revision contains the log message you wrote, plus any
subsequent changes you made.


When @code{reply} wants to apply a patch set, it checks to see if it is an
idempotent patch set.  If it is, and all of the patches included in
the patch set are missing from the tree being patched, @code{replay}
proceeds in the usual way: by applying the set of deltas in the patch
set.


If some of the patches included in an idempotent merge have already
been applied to the tree being patched, then `@code{replay} applies only
those patches not already included.


One possible policy is that every branch should merge only from the
main branch, and should always merge from the main branch using an
idempotent update:

@example
@group
        % cd ~/wd
@end group
@group
@end group
@end example
@example
@group
        % larch i-merge --update main branch-a branch-a-merged
        [...]
@end group
@group
@end group
@end example

Each branch will then contain a number of idempotent patch sets, as in
this example:

@example
@group
        branch-a                                            branch-b
        --------                                            --------
        base-0                                              base-0
        patch-1                                             patch-1
        patch-2..."idempotent merge w/main patches 2,3"     patch-2
@end group
@group
        patch-3         "idempotent merge w/main patch 2"...patch-3
        patch-4                                             patch-4
        patch-5..."idempotent merge w/main patch 4"         patch-5
@end group
@group
        patch-6         "idempotent merge w/main patch 3"...patch-6
        patch-7..."idempotent merge w/main patch 5"         patch-7
        patch-8                                             patch-8
                    "idempotent merge w/main patches 4,5"...patch-9
                                                            patch-10
@end group
@group
@end group
@end example

What if we want to form a merge of these two branches?




@need 3200

@section idempotent Merges and the replay Command

We can start with a project tree for the latest revision of @code{branch-a}

@example
@group
        % larch get ~/wd/branch-a
        % cd ~/wd/branch-a
@end group
@group
@end group
@end example

@code{Branch-a} does not already have a patch log for @code{branch-b}, though
the two branches have a common ancestor, so @code{add-sibling-log} will
solve that problem:

@example
@group
        % larch add-sibling-log branch-b
        [....]
@end group
@group
@end group
@end example

Now we can find out what the merge needs to do:

@example
@group
        % larch whats-missing branch-b
        patch-1
        patch-2
        patch-3
        patch-4
@end group
@group
        patch-5
@end group
@group
        patch-6
        patch-7
        patch-8
        patch-9
        patch-10
@end group
@group
@end group
@end example

If we use @code{replay}:

@example
@group
        % cd ~/wd
        % larch replay ~/wd/branch-a ~/wd/branch-a-merged branch-b
@end group
@group
@end group
@end example

These patches will be applied:

@example
@group
        branch-b/patch-1
        branch-b/patch-2
        branch-b/patch-4
        branch-b/patch-5
        branch-b/patch-7
        branch-b/patch-8
        branch-b/patch-10
@end group
@group
@end group
@end example

Patches @code{3, 6, 9} are skipped (though their log entries are added to
the project tree) because branch-a already has all of the patches
those idempotent patch sets include.




@need 3200

@section idempotent Patch Sets and the update Command

What will @code{update} do?  It computes a patch between the project tree
being updated and the common ancestor:

@example
@group
        update_patch = delta (branch-a--patch-8, branch-b--base-0)
@end group
@group
@end group
@end example

@noindent
then applies that to the update revision:

@example
@group
        branch-a-mege  = update_patch [ branch-b--patch-10 ]
@end group
@group
@end group
@end example

The idempotent revisions don't help there.  However....




@need 3200

@section idempotent Patch Sets and Partial Updates

The @code{--partial} flag to the @code{update} command takes advantage of
idempotent patch sets.


As before, we assume these revisions:

@example
@group
        branch-a                                            branch-b
        --------                                            --------
        base-0                                              base-0
        patch-1                                             patch-1
        patch-2..."idempotent merge w/main patches 2,3"     patch-2
@end group
@group
        patch-3         "idempotent merge w/main patch 2"...patch-3
        patch-4                                             patch-4
        patch-5..."idempotent merge w/main patch 4"         patch-5
@end group
@group
        patch-6         "idempotent merge w/main patch 3"...patch-6
        patch-7..."idempotent merge w/main patch 5"         patch-7
        patch-8                                             patch-8
                    "idempotent merge w/main patches 4,5"...patch-9
                                                            patch-10
@end group
@group
@end group
@end example

We have a tree for @code{branch-a--patch-8} and it's ancestor on @code{branch-b}
is @code{base-0}.  So:

@example
@group
        % cd ~/wd/branch-a--patch-8
        % larch whats-missing branch-b
        patch-1
        patch-2
        patch-3
        patch-4
        patch-5
        [...]
        patch-10
@end group
@group
@end group
@end example

If we use:

@example
@group
        % larch update --partial ~/wd/branch-a--patch-8 \
                                ~/wd/branch-a-b-partial-update \
                                branch-b
@end group
@group
@end group
@end example

@noindent
then @code{update} uses not the latest revision of @code{branch-b}, but the
revision just prior to the oldest idempotent patch set that @code{branch-a}
does not yet have.  In this case, @code{patch-3} of branch-b is the oldest
idempotent patch that @code{branch-a} is missing.  So:

@example
@group
        % larch update --partial ~/wd/branch-a--patch-8 \
                                ~/wd/branch-a-b-partial-update \
                                branch-b
@end group
@group
@end group
@end example

@noindent
is eqivalent to:

@example
@group
        % larch update --partial ~/wd/branch-a--patch-8 \
                                ~/wd/branch-a-b-partial-update \
                                branch-b--patch-2
@end group
@group
@end group
@end example

After which:

@example
@group
        % cd ~/wd/branch-a-b-partial-update
        % larch whats-missing branch-b
        patch-3
        patch-4
        patch-5
        [...]
        patch-10
@end group
@group
@end group
@end example

When the earliest missing patch prior to a partial update is an
idempotent patch set, and the tree already has all of the patches
included in that patch set, @code{update} simply adds the log message for
the idempotent patch to the tree being patched, and stops.


If the tree being patched has @emph{none} of the patches included in that
patch set, @code{update} updates against the idempotent revision in the
normal way.


Finally, if the tree being patch has @emph{some} but not all of the patches
included in the idempotent patch set, @code{udpate} gives up with an error
and suggests that you use @code{replay} to apply the idempotent patch set.
(In a future release, @code{update} will do something more intellegent in
this case).


The upshot of this is that you can merge branches @code{A} and @code{B} with a
series of partial updates and replays:

@example
@group
        # update against patch-level 2
        # 
        % larch update --partial ~/wd/branch-a--patch-8
                                ~/wd/branch-a-b-partial-update
                                branch-b
@end group
@group
@end group
@end example
@example
@group
        # replay patch-level 3
        #   -- we already have all the patches included in the
        #      idempotent branch-b patch, "patch-3" - so all this
        #      really does is install a log message.
        # 
        % larch replay ~/wd/branch-a-b-partial-update
                      ~/wd/branch-a-b-partial-update-2
                      branch-b--patch-3
@end group
@group
@end group
@end example
@example
@group
        # update against patch-level 5
        # 
        % larch update --partial ~/wd/branch-a-b-partial-update-2
                                ~/wd/branch-a-b-partial-update-3
                                branch-b
@end group
@group
@end group
@end example
@example
@group
        % larch replay ~/wd/branch-a-b-partial-update-3
                      ~/wd/branch-a-b-partial-update-4
                      branch-b--patch-5
@end group
@group
@end group
@end example
@example
@group
        % larch update --partial ~/wd/branch-a-b-partial-update-5
                                ~/wd/branch-a-b-partial-update-6
                                branch-b
@end group
@group
@end group
@end example
@example
@group
        % larch replay ~/wd/branch-a-b-partial-update-6
                      ~/wd/branch-a-b-partial-update-7
                      branch-b--patch-9
@end group
@group
@end group
@end example
@example
@group
        % larch update --partial ~/wd/branch-a-b-partial-update-9
                                ~/wd/branch-a-b-merged
                                branch-b
@end group
@group
@end group
@end example






