Checking-in Changes

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.