Next: Retrieving Earlier Revisions, Up: Working With Arch
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.
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.
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 in 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 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.
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.
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.
So now let's record those changes in the archive.
If you didn't take our free advice (see Messages
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
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.