The previous chapter introduced changesets and the commands
dopatch (fancy variations on the theme of the
In this chapter, we'll look in a bit more detail about how changesets
are used in archives, how they are used by the
commands, and what this implies for how you can make the best use of
Suppose that you
get the latest revision of a project, make some
changes, write a log message, and
commit those changes to an
archive. What happens?
In essence, commit:
1 Computes a changeset that describes what changes you've made compared to the latest revision.
2 Creates a directory for the new revision in the archive.
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: How it Works – commit of a New Revision in Checking-in Changes.
Earlier, you learned that the
cat-archive-log command retrieves a
log message from an archive (see Studying Why Alice Can Not commit in The update/commit Style of Cooperation).
You can also retrieve a changeset from an archive:
% cd ~/wd % tla get-changeset hello-world--mainline--0.1--patch-1 patch-1 [...]
get-changeset retrieves the changeset from the archive and, in this
case, stores it in a directory called
(The format of changesets is described in The arch Changeset Format.)
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:
% tla show-changeset --diffs patch-1
If you've been following along with the examples, you'll recognize the
output format of
show-changeset from the
changes command introduced
earlier (see Oh My Gosh – What Have I Done? in Checking-in Changes).
When you commit a set of changes, it is generally "best practice" to make sure you are creating a 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
There are many advantages to clean changesets but foremost among them are:
Easier Review It is easy for someone to understand a changeset if it is only trying to do one thing.
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 cherrypicking is much more practical.