[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

Tutorial

In this tutorial, we are going to create an archive, put a simple program into it, and then create successive revisions and branches. This uses the bash shell. Different shells may require you to quote special characters differently.


Creating the first revision

We start with creating an archive. First, we have to tell arx who we are

 
        % arx my-id 'J. Hacker <jhacker@foobar.org>'

You should also tell arx what kind of editor you like to use for editing logs etc. If you already have the $EDITOR or $ARCHEDITOR shell variables set, then you can skip this step. To set arx to use emacs, for example, you use the my-editor command

 
        % arx my-editor emacs

and if you're a vi user, you can type

 
        % arx my-editor vi

Now we create an archive

 
        % arx make-archive jhacker@foobar.org--archive {archive}

This creates an archive in the directory {archive}. Normally, you should never need to look in that directory.

Next, we make that archive our default archive

 
        % arx my-default-archive jhacker@foobar.org--archive

Now we want to make a revision library. You may not always need this, but it is often a nice feature if you have a lot of revisions that you want to look at.

 
        % mkdir "{revisions}"

Then we tell arx about it

 
         % arx my-revision-library "`pwd`/{revisions}"

Finally, we can start writing a program. We will use the simplest shell script, Hello world. First, we create a directory to house the project.

 
        % mkdir hello

Then we create the program

 
        % cd hello
        % echo "echo Hello, World" > Hello

Now we are going to store this masterpiece in arx. We first have to create a log, letting ArX know that we are creating a new project. We will call the project "hello". Since it is the main line of development, we will call the branch "main". Since it is feature complete, we make the version 1.0.

 
        % arx create-version hello--main--1.0

This opens the log file in the editor that you specified earlier. It also creates an {arch} sub-directory in the current directory. You should never need to look at things in this directory.

You can edit the log file, ++log.hello--main--1.0--jhacker@foobar.org--archive in this case. You have to be sure to put something in the Summary: line. Also, you have to skip a line between headers (like Summary: and Keywords:) and the body. Otherwise the commit into arx won't work.

Alternately, we can just execute

 
        % echo "Summary: initial" \
        > ./`arx create-version --non-interactive hello--main--1.0`

The --non-interactive option prevents arx from running the editor. Instead it just prints the name of the log file to standard output.

If you wanted to have a multi-line Summary:, you can continue by indenting the next line. As an example,

 
        Summary: initial version of the foo-bar-baz program,
          which does foo, bar and baz.

Now we have to register our file with arx

 
        % arx add Hello

Finally, you can now archive the program in arx by running

 
        % arx commit


Revisions

Now that you've archived the program, you've realized that you don't like the comma in "Hello, World", and you like it to output "Hello World". So you edit Hello, or just run

 
        % echo "echo Hello World" > Hello

You need to make a log file, so you run either

 
        % arx make-log

and edit the file ++log.hello--main--1.0--jhacker@foobar.org--archive, or just run

 
        % echo "Summary: Removed a comma" > `arx make-log --non-interactive`

Then you commit the change

 
        % arx commit

Now you get the idea for a bigger change. You want to make the program say goodbye. So you edit the program again

 
        % echo "echo Hello World.  Goodbye" > Hello

Since this is major change, you decide to bump the version number to 1.1. You do this just by using create-version again with a new version number

 
        % arx create-version hello--main--1.1

and editing the file, or just running

 
        % echo "Summary: Added goodbye" \
        > `arx create-version --non-interactive hello--main--1.1`

Then you commit the change for the new version.

 
        % arx commit


Branches

Now you've decided that you want to internationalize your program. So you want to create a german version. Since this version will have a lot of parts that won't be shared with the english version, you decide to make a branch. Your german is pretty rusty, and you've forgotten how to spell Auf Wiedersehen, so you decide to branch from the older, simpler version without goodbye. The simplest way to do this is to go into the parent directory and create a branch

 
        % cd ..
        % arx create-branch hello--main--1.0 hello--german--1.0 \
        hello--german

This creates a directory hello-german and pops up an editor to edit the log file. You can also do it non-interactively

 
        % echo "Summary: German version" \
        > `arx create-branch hello--main--1.0 hello--german--1.0 \
        hello--german`

Now change into the directory and commit the new branch

 
        % cd hello--german
        % arx commit

Now you can edit the program, create a log, and commit a change as normal.

 
        % echo "echo Guten Tag" > Hello
        % echo "Summary: Translated" > `arx make-log --non-interactive`
        % arx commit


Wrapping up

Congratulations. You have now created a project, made revisions, changed the version number, and created a branch. You can view what versions are in the archive with

 
        % arx versions

It should echo

 
        hello--german--1.0

It only looked at the german line of development because your current directory (project tree) version is set to hello--german--1.0. We can look at the main line of development by specifying it explicitly.

 
        % arx versions hello--main

and it should echo

 
        hello--main--1.0
        hello--main--1.1

We can see what revisions were made to hello--main--1.0

 
        % arx revisions hello--main--1.0
        base-0
        patch-1

We can see what branches have been made

 
        % arx branches
        hello--german
        hello--main

Finally, we can see what projects we have

 
        % arx categories
        hello


Revision Trees

Now suppose you have forgotten what things looked like in hello--main--1.0. A simple way to view them is with revision trees. It is a complete version of the source tree for a particular revision. For successive revisions, arx uses hard links to prevent unnecessary copying. To create a revision for hello--main--1.0--base-0, it is simply

 
        % arx library-add hello--main--1.0--base-0

To view the original version of the file, then is just

 
        % more ../\{revisions\}/jhacker@foobar.org--archive/\
          hello/hello--main/hello--main--1.0/\
          hello--main--1.0--base-0/Hello 


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Walter Landry on April, 30 2003 using texi2html