The Hackerlab at `regexps.com`

## Exploring Changesets

up: arch Meets hello-world next: Introducing replay -- An Alternative to update prev: Introducing 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` .

### 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.

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

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

### 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?).

### 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.

arch Meets hello-world: A Tutorial Introduction to The arch Revision Control System
The Hackerlab at `regexps.com`