@need 3200

@node Checking-in Changes
@chapter Checking-in Changes

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


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

@need 3200

@section warld != world\n

If you look at our @code{hello-world} sources, you might notice a spelling
error and newline bug:

@example
@group
        % cat hw.c
@end group
@group

@end group
@group
        #include <stdio.h>
@end group
@group

@end group
@group
        void
        hello_world (void)
        @{
          (void)printf ("hello warld");
        @}
@end group
@group

        
@end group
@group
        /*tag: hello_world module of the hello-world project
         */
/************************************************************************
 *(h1 "Some Free Advice About Log Messages")
 * 
@end group
@group

@end group
@group
 * *Free advice is worth what you pay for it.* -- anonymous.
@end group
@group

@end group
@group
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.
@end group
@group

@end group
@group
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").
@end group
@group

@end group
@group
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.
@end group
@group

@end group
@group
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:
@end group
@group


@end group
@group
insert*/
        % cd ~/wd/hello-world
@end group
@group

@end group
@group
        % larch make-log
        ++log.hello-world--mainline--0.1--lord@@emf.net--2003-example
@end group
@group

@end group
@end example

Then edit your new log file so that it reads:

@example
@group
        Summary: Fix bugs in the "hello world" string
        Keywords: 
@end group
@group
@end group
@end example

The @code{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.




@need 3200

@section The Edit/Update-Log Cycle

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


@strong{Fix the spelling error.}  Change @code{warld} to @code{world}.


@strong{Update the log message.}  Add a note to the log file:

@example
@group
        Summary: Fix bugs in the "hello world" string
        Keywords: 
@end group
@group

@end group
@group
        Spell "world" correctly (not "warld").
@end group
@group

@end group
@end example

@strong{Fix the newline error.}  Add a newline to the message.


@strong{Update the log message again.} Add a note to the log file:

@example
@group
        Summary: Fix bugs in the "hello world" string
        Keywords: 
@end group
@group

@end group
@group
        Spell "world" correctly (not "warld").
@end group
@group

@end group
@group
        Add a newline to the hello world message.
@end group
@group

@end group
@end example



@need 3200

@section Oh My Gosh -- What Have I Done?

@geindex what-changed



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, @code{arch} can help:

@example
@group
        % larch what-changed --diffs
        [....]
        *** patched regular files
@end group
@group
 
@end group
@group
        **** ./hw.c
        [....] 
             @@@@ -4,7 +4,7 @@@@
              void
              hello_world (void)
@end group
@group
              @{
             -  (void)printf ("hello warld");
             +  (void)printf ("hello world\n");
              @}
        [....]
@end group
@group


@end group
@end example

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




@need 3200

@section Storing Changes in the Archive

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


If you didn't take our free advice (see @geindex Some Free Advice About Log
Messages
@dfn{Some Free Advice About Log
Messages}), now is the time to create a log message (hint: use @code{larch
make-log}).


To save your changes in the archive, simply:

@example
@group
        % larch commit
        [....]
@end group
@group
@end group
@end example

After the @code{commit} completes, there is a new revision in the archive:

@example
@group
        % larch revisions hello-world--mainline--0.1
        base-0
        patch-1
@end group
@group
@end group
@end example

@noindent
or in more detail:

@example
@group
        % larch revisions --summary hello-world--mainline--0.1
        base-0
            initial import
        patch-1
            Fix bugs in the "hello world" string
@end group
@group
@end group
@end example

Our project tree patch log has been similarly updated:

@example
@group
        % larch log-ls hello-world--mainline--0.1
        base-0
        patch-1
@end group
@group

@end group
@group
        % larch log-ls --summary hello-world--mainline--0.1
        base-0
            initial import
        patch-1
            Fix bugs in the "hello world" string
@end group
@group

@end group
@end example



@need 3200

@section How it Works -- commit of a New Revision

What does @code{commit} do to an archive?

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

The @code{patch-1} subdirectory is new:

@example
@group
        % cd patch-1
@end group
@group

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

@end group
@end example

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

@example
@group
        % 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
@end group
@group
        Standard-date: 2003-01-28 06:26:13 GMT
        Summary: Fix bugs in the "hello world" string
        Keywords: 
@end group
@group
        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
@end group
@group

@end group
@group
        Spell "world" correctly (not "warld").
@end group
@group

@end group
@group
        Add a newline to the hello world message.
@end group
@group


@end group
@end example

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


In the project tree:

@example
@group
        % cd ~/wd/hello-world
@end group
@group
@end group
@end example

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







