@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
@end example

Clearly, we meant to say @code{hello world}, not @code{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.




@need 3200

@section Some Free Advice About Log Messages

@emph{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 @code{arch} to record the changes need to fix the
bugs in the archive.    That second step will create a new @emph{revision}
in the archive.


As we noted earlier, whenever you create a new revision, you need to
provide a @emph{log message} for that revision (see @strong{Making the First Log File} in @ref{Importing the First Revision}).


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 @code{tla} commands, 
that means to start the bug fix process with:

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

@end group
@group
        tla 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 changes



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
        tla changes --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: @code{tla
make-log}).


To save your changes in the archive, simply:

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

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

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

@noindent
or in more detail:

@example
@group
        % tla 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
        % tla logs hello-world--mainline--0.1
        base-0
        patch-1
@end group
@group

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







