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");
            }

            /*tag: hello_world module of the hello-world project
             */
    /************************************************************************
     *(h1 "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 xref:"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 `larch' commands,
    that means to start the bug fix process with:

    insert*/
            % cd ~/wd/hello-world

            % larch 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:

            % larch what-changed --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: use `larch make-log` ).

To save your changes in the archive, simply:

            % larch commit
            [....]

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

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

or in more detail:

            % larch 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:

            % larch log-ls hello-world--mainline--0.1
            base-0
            patch-1

            % larch log-ls --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`