A.3 Exploring Changesets

The previous chapter introduced changesets and the commands mkpatch and dopatch (fancy variations on the theme of the traditional diff and 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 commit and update commands, and what this implies for how you can make the best use of arch.

A.3.1 How it Works – commit Stores a Changeset in the Archive

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.

A.3.2 get-changeset Retrieves a Changeset from an Archive

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 patch-1.

(The format of changesets is described in The arch Changeset Format.)

A.3.3 Using show-changeset to Examine a 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:

             % 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).

A.3.4 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 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 commit.

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.