The Hackerlab at `regexps.com`

## Starting a New Source Tree

up: arch Meets hello-world next: Project Tree Inventories prev: Starting a New Project

After following the examples in earlier chapters, you should have a new archive and new `hello-world` project within that archive.

In this chapter, we'll walk through the steps of preparing a source tree to be part of that project.

### The Intial Source

For the sake of example, let's assume that we have an initial, slightly buggy, implementation of `hello-world` :

            % cd ~/wd

            % ls
            hello-world

            % cd hello-world

            % ls
            hw.c    main.c

            % cat hw.c

            #include <stdio.h>

            void
            hello_world (void)
            {
              (void)printf ("hello warld");
            }

            % cat main.c

            extern void hello_world (void);

            int
            main (int argc, char * argv[])
            {
              hello_world ();
              return 0;
            }

### Initializing a Project Tree

The first step of preparing source is to turn the ordinary source tree into a project tree :

            % cd ~/wd/hello-world

            % tla init-tree hello-world--mainline--0.1

            % ls
            hw.c    main.c  {arch}

Note that we passed `init-tree` the name of the version in the archive that we'll be working on. `init-tree` created a new subdirectory in the root of the tree (`{arch}` ).

The `{arch}` subdirectory indicates that this is the root of a project tree:

            % tla tree-root
            /usr/lord/wd/hello-world

`tla` knows what archive version this tree is for:

            % tla tree-version
            lord@emf.net--2003-example/hello-world--mainline--0.1

Finally, `arch` has created something called a patch log for the version passed to `init-tree` :

            % tla log-versions
            lord@emf.net--2003-example/hello-world--mainline--0.1

We'll explain what patch logs are for in later chapters.

### Initializing a Tree Does Not Change an Archive

So far, we've only marked the project tree as source: we haven't yet stored anything new in the archive. We'll get there, but before we do that, there's an important topic to cover first: source inventories. We'll cover that in the next chapter.

### What if You Make a Mistake With init-tree?

Suppose that in the example above, we had mis-typed:

            % tla init-tree hello-world--mainlin--0.1

One "brute force" solution is just to delete the `{arch}` subdirectory and start over. Later on, though, that solution is undesirable: the `{arch}` subdirectory may contain some data you don't want to delete. So, we'll take this opportunity to introduce a few more advanced commands.

There are two problems after the bogus call to `init-tree` . The output from both of these commands is not what we want:

            % tla tree-version
            lord@emf.net--2003-example/hello-world--mainlin--0.1

            % tla log-versions
            lord@emf.net--2003-example/hello-world--mainlin--0.1

We can change the `tree-version` of a tree at any time:

            % tla set-tree-version hello-world--mainline--0.1

            % tla tree-version
            lord@emf.net--2003-example/hello-world--mainline--0.1

Patch logs are a little trickier. We have to delete the logs we don't want, and add those that we do want:

            % tla add-log-version hello-world--mainline--0.1

            % tla log-versions
            lord@emf.net--2003-example/hello-world--mainlin--0.1
            lord@emf.net--2003-example/hello-world--mainline--0.1

            % tla remove-log-version hello-world--mainlin--0.1

            % tla log-versions
            lord@emf.net--2003-example/hello-world--mainline--0.1

WARNING: `remove-log-version` is a dangerous command: it will remove patch logs that you might need if you ask it to. You should only use `remove-log-version` when you are certain, as we were above, that what is being removed is one you do not want.

### How it Works -- Initializing a New Tree

`init-tree` created the `{arch}` subdirectory at the root of the source tree. What's in there?

            % ls {arch}
            ++default-version       =tagging-method         hello-world

            % cat {arch}/++default-version
            lord@emf.net--2003-example/hello-world--mainline--0.1

            % cat {arch}/=tagging-method
            [... long output ...]

`{arch}/hello-world` is the root of a fairly deep tree. Patch logs are stored within that tree.

`{arch}/=tagging-method` is a configuration file that you can use to customize the naming conventions that apply to this tree. It is explained in a later chapter (see Customizing the inventory Naming Conventions).

Note: You should not, of course, edit the contents of the `{arch}` directory by hand.

arch Meets hello-world: A Tutorial Introduction to The arch Revision Control System
The Hackerlab at `regexps.com`