@need 3200

@node Cherrypicking Changes
@chapter Cherrypicking Changes

@geindex replay --exact



So far we've learned about elementary branches for maintaining changes
apart from a primary development branch and development branches for
coordinating asynchronous work on a single project (see
@ref{Elementary Branches -- Maintaining Private Changes} and
@ref{Development Branches -- The star-merge Style of Cooperation}).


In this chapter, we'll briefly describe a third kind of branch that's
useful when a project consists of multiple "forks" -- multiple,
equally primary branches.


Let's suppose, somewhat abstractly, that Alice and Bob's mainline has
grown quite large:

@example
@group

@end group
@group
        mainline
        --------
        base-0
        patch-1
        ....
@end group
@group
        patch-23
        patch-24
        patch-25
        ...
        patch-42
@end group
@group


@end group
@end example

At some point, perhaps because some controversy has emerged over
choices made in the @code{mainline}, a new developer, Derick, declares 
a fork and starts his own branch:

@example
@group

@end group
@group
        mainline                derick
        --------                ------
        base-0          ------> base-0
        patch-1        '
        ....          '
@end group
@group
        patch-23 ----'
        patch-24
        patch-25
        ...
        patch-42
@end group
@group


@end group
@end example

We already know that Derick can use @code{update} or @code{replay} to keep
current with the mainline, but what he doesn't want to?   What if
Derick wants the changes in @code{patch-25} and @code{patch-42}, but none of the
other post-@code{patch-23} changes from the @code{mainline}?


Derick can apply specific changes from the @code{mainline} by using the
@code{--exact} option to @code{replay}:

@example
@group

@end group
@group
        % cd ~/wd
@end group
@group

@end group
@group
        % larch get hello-world--derick--0.1 derick
@end group
@group

@end group
@group
        % cd derick
@end group
@group

@end group
@group
        % larch replay --exact -A lord@@emf.net--2003-example \
                 hello-world--mainline--0.1--patch-23
@end group
@group

@end group
@group
        % larch replay --exact -A lord@@emf.net--2003-example \
                 hello-world--mainline--0.1--patch-42
@end group
@group

@end group
@group
        % larch whats-missing -A lord@@emf.net--2003-example \
                 hello-world--mainline--0.1
        patch-24
        patch-25
        ...
        patch-41
@end group
@group


@end group
@group
        % larch log-ls -A lord@@emf.net--2003-example \
                 hello-world--mainline--0.1
        base-0
        patch-1
        ...
        patch-22
        patch-23
        patch-42
@end group
@group


@end group
@end example

@geindex Cherrypicking
@dfn{Cherrypicking} changes in this manner isn't necessarily easy or even
practical.  It depends, for example, on the @code{mainline} changes being
"clean changesets" (see @strong{Using commit Well -- The Idea of a Clean Changeset} in @ref{Exploring Changesets}).


Nevertheless, for some projects, especially those characterized by
lots of "forks", this technique can be useful.


@strong{Learning Note:}  The @code{replay} command also has a @code{--list} option
which can useful for cherrypicking many changes at once.  If you find
yourself using @code{replay --exact} often, you should take a look at the
@code{--list} option in @code{larch replay --help}.




