The Hackerlab at `regexps.com`

## Checking-in Changes

up: arch Meets hello-world next: Retrieving Earlier Revisions prev: Importing the First Revision

So far, if you're following the examples, we've created a new archive and a `hello-world` project within that archive, and we've imported the initial version of `hello-world` into the archive.

The most common task you're likely to perform as a programming using a revision control system is to commit a set of changes. In this chapter, we'll look at the most basic way that that works.

### warld != world\n

If you look at our `hello-world` sources, you might notice a spelling error and newline bug:

            % cat hw.c

            #include <stdio.h>

            void
            hello_world (void)
            {
              (void)printf ("hello warld");
            }

Clearly, we meant to say `hello world` , not `hello warld` and, if we're going to be conventional, we probably wanted a newline at the end of the message. So, let's fix those bugs now.

### Some Free Advice About Log Messages

Free advice is worth what you pay for it. -- anonymous.

Here's the plan for fixing these bugs: We'll change the source to fix the bugs. Then we'll ask `arch` to record the changes need to fix the bugs in the archive. That second step will create a new revision in the archive.

As we noted earlier, whenever you create a new revision, you need to provide a log message for that revision (see Making the First Log File).

The particular bugs we're about to fix in our toy example are quite trivial -- but in a real world situation, they would likely be more complicated. You have a choice: you can either wait until all the changes are done to write the log message describing your changes, or you can write the log message as you go along.

Here's the free advice: write the log message as you go along. In other words, take notes as you hack. In terms of `tla` commands, that means to start the bug fix process with:

            % cd ~/wd/hello-world

            tla make-log
            ++log.hello-world--mainline--0.1--lord@emf.net--2003-example

Then edit your new log file so that it reads:

            Summary: Fix bugs in the "hello world" string
            Keywords:

The `Summary:` thus explains what you intend to do with the upcoming changes. As you work, you can fill in the body of the log message.

### The Edit/Update-Log Cycle

Pretending that these bugs are more complicated than they actually are, here's how the work might go:

Fix the spelling error. Change `warld` to `world` .

Update the log message. Add a note to the log file:

            Summary: Fix bugs in the "hello world" string
            Keywords:

            Spell "world" correctly (not "warld").

Fix the newline error. Add a newline to the message.

Update the log message again. Add a note to the log file:

            Summary: Fix bugs in the "hello world" string
            Keywords:

            Spell "world" correctly (not "warld").

            Add a newline to the hello world message.

### Oh My Gosh -- What Have I Done?

So you've just worked long and hard on these complex bug fixes. Wouldn't it be a good idea to review your work once more before publishing it?

No problem, `arch` can help:

            tla changes --diffs
            [....]
            *** patched regular files

            **** ./hw.c
            [....]
                 @@ -4,7 +4,7 @@
                  void
                  hello_world (void)
                  {
                 -  (void)printf ("hello warld");
                 +  (void)printf ("hello world\n");
                  }
            [....]

Aha! Now we know. It's time to record that change in the archive.

### Storing Changes in the Archive

So now let's record those changes in the archive.

If you didn't take our free advice (see Some Free Advice About Log Messages ), now is the time to create a log message (hint: `tla make-log` ).

To save your changes in the archive, simply:

            % tla commit
            [....]

After the `commit` completes, there is a new revision in the archive:

            % tla revisions hello-world--mainline--0.1
            base-0
            patch-1

or in more detail:

            % tla revisions --summary hello-world--mainline--0.1
            base-0
                initial import
            patch-1
                Fix bugs in the "hello world" string

Our project tree patch log has been similarly updated:

            % tla logs hello-world--mainline--0.1
            base-0
            patch-1

            % tla logs --summary hello-world--mainline--0.1
            base-0
                initial import
            patch-1
                Fix bugs in the "hello world" string

### How it Works -- commit of a New Revision

What does `commit` do to an archive?

            # cd to the directory for the version we are working
            # on:
            #
            % cd ~/{archives}
            % cd 2003-example/
            % cd hello-world/
            % cd hello-world--mainline/
            % cd hello-world--mainline--0.1/
            % ls
            % ls
            +version-lock   =README         base-0          patch-1

The `patch-1` subdirectory is new:

            % cd patch-1

            % ls
            +revision-lock
            hello-world--mainline--0.1--patch-1.patches.tar.gz
            log

As usual, the log file is the log file you wrote, with some extra headers added:

            % cat log
            Revision: hello-world--mainline--0.1--patch-1
            Archive: lord@emf.net--2003-example
            Creator: Tom (testing) Lord <lord@emf.net>
            Date: Mon Jan 27 22:26:13 PST 2003
            Standard-date: 2003-01-28 06:26:13 GMT
            Summary: Fix bugs in the "hello world" string
            Keywords:
            New-files: \
              {arch}/hello-world/ [....] /patch-log/patch-1
            Modified-files: hw.c
            New-patches: \
              lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1

            Spell "world" correctly (not "warld").

            Add a newline to the hello world message.

The `.patches.tar.gz` file is something called a changeset. It describes the changes you made as differences between the `base-0` revision and the `patch-1` revision. You'll learn more about the nature of changesets in later chapters. For now, you can think of a changeset as similar to the output of `diff -r` if used to compare the `base-0` revision before your recent changes, with that same tree after your recent changes (or, in the words of one `arch` user: a "patch set on steroids").

In the project tree:

            % cd ~/wd/hello-world

the commit command had two effects. First, it added a log file under `{arch}/hello-world` . Second, it modified `{arch}/++pristine-trees` to contain a cached copy of the `patch-1` revision instead of the `base-0` revision.

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