@need 3200

@node Exploring Changesets
@chapter Exploring Changesets

The previous chapter introduced @emph{changesets} and the commands
@code{mkpatch} and @code{dopatch} (fancy variations on the theme of the
traditional @code{diff} and @code{patch} programs).


In this chapter, we'll look in a bit more detail about how changesets
are used in archives, how they are used by the @code{commit} and @code{update}
commands, and what this implies for how you can make the best use of
@code{arch}.

@need 3200

@section How it Works -- commit Stores a Changeset in the Archive

Suppose that you @code{get} the latest revision of a project, make some
changes, write a log message, and @code{commit} those changes to an
archive.   What happens?


In essence, commit:


@strong{1} Computes a changeset that describes what changes you've made
compared to the latest revision.


@strong{2} Creates a directory for the new revision in the archive.


@strong{3} Stores your log message and the changeset in the archive.


In that light, you might want to go back and review an earlier
section: @strong{How it Works -- commit of a New Revision} in @ref{Checking-in Changes}.




@need 3200

@section get-changeset Retrieves a Changeset from an Archive

@geindex get-changeset



Earlier, you learned that the @code{cat-archive-log} command retrieves a
log message from an archive (see @strong{Studying Why Alice Can Not commit} in @ref{The update/commit Style of Cooperation}).


You can also retrieve a changeset from an archive:

@example
@group

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

@end group
@group
        % tla get-changeset hello-world--mainline--0.1--patch-1 patch-1
        [...]
@end group
@group

@end group
@end example

@code{get-changeset} retrieves the changeset from the archive and, in this
case, stores it in a directory called @code{patch-1}.


(The format of changesets is described in @ref{The arch Changeset Format}.)




@need 3200

@section Using show-changeset to Examine a Changeset

@geindex show-changeset



The changeset format is optimized for use by programs, not people.
It's awkward to look at a changeset "by hand".   Instead, you 
may wish to consider getting a report of the patch in diff format 
by using:

@example
@group
        % tla show-changeset --diffs patch-1
@end group
@group
@end group
@end example
@example
@group
        [...]
@end group
@group
@end group
@end example

If you've been following along with the examples, you'll recognize the
output format of @code{show-changeset} from the @code{changes} command introduced
earlier (see @strong{Oh My Gosh -- What Have I Done?} in @ref{Checking-in Changes}).




@need 3200

@section Using commit Well -- The Idea of a Clean Changeset

When you commit a set of changes, it is generally "best practice" to
make sure you are creating a @geindex clean changeset
@dfn{clean changeset}.


A clean changeset is one that contains only changes that are all
related and for a single purpose.   For example, if you have several
bugs to fix, or several features to add, try not to mix those changes
up in a single @code{commit}.


There are many advantages to clean changesets but foremost among them
are:


@strong{Easier Review}  It is easy for someone to understand a changeset if
it is only trying to do one thing.


@strong{Easier Merging} As we'll learn in later chapters, there are
circumstances in which you'll want to look at a collection of
changesets in an archive and pick-and-choose among them.  Perhaps you
want to grab "bug fix A" but not "new feature B".   If each
changeset has only one purpose, that kind of @geindex cherrypicking
@dfn{cherrypicking} is much
more practical.







