Quick Start with Archipel

This section will guide you through the steps involved in a basic usage of Archipel. You will learn how to create and setup an Archipel project, how to track changes, commit changes, checkout particular versions and distribute your changes to other developers.

Whenever you encounter a term that might be difficult to understand, you can refere to the ArchipelTerminology.

Conventions

This sections presents Archipel command-line usage. Every example is given using a relatively simple syntax:

archipel [command] [arguments]

Where something between [ and ] is a value of the given type. This "something" can be assigned a cardinality.

For instance,

archipel status [file|directory]+

indicates that the status command of Archipel can take 1 to many argumens of type file or directory, which are the two basic types (with litteral, meaning a text string) that Archipel commands can take.

1. Creating a project

Creating a new project in archipel is dead simple, you just have to cd to the directory you want to put under version control, and type

 archipel create [name] 

where name is your project name. Typing archipel create MyProject? will create a MyProject?.archipel file in the current directory.

Alternatively, if you do not want to put the current directory under control, you can specify explicitely another directory with

 achipel create [name] [directory]

where directory is the path to the directory (your project directory) that you want to put under version control. In this case, the project file will also be created in the designated directory.

Once the project file is created, you can issue any other archipel command as long as you type them in the directory containing the project file, or in any of its subdirectories.

2. Assigning a repository

When you create a new Archipel project, the project needs a place to store the versionning information. This place is caleld the repository.

A repository is simply a directory on your local filesystem that holds all the information needed to restore previous states of your project.

By default, the project repository is located in your project root directory, and is name MyProject?.repostory, where you replace MyProject? by your actual project name. If the ARCHIPEL_REPOSITORY environment variable is defined, the repository will instead be located at the value of this variable. Note that a directory can be shared by multiple projects.

To determine the project that was assigned to your project, you can type the following command:

 archipel repository status

If you want to specify another location for your repository, you can type the following command:

 archipel repository set [location]

which will set the repository to be the given location. If the given repository does not exist, it will be created, otherwise the existing repository will be used. Once that a project was created an assigned a repository, you can put files and directories under version control.

Note that you can change the repository location at any time during your project lifecycle. In some cases, Archipel will move or copy information from your old repository to the new one. Also, it you can note that repositories are not created until first commit, so that changing your repository location will not spoil your filesystem at project creation.

3. Putting files and directories under version control

By default, Archipel does not track any file in your newly created project. You have to indicate which files you want it to track, using the track command

 archipel track [file|directory]+

Conversly, if you do not want to track a file or a directory anymore, you can use the untrack command

 archipel untrack [file|directory]+

When you untrack a file or a directory, you can still re-track it later and keep its history. In most cases, this will be automatically made by archipel.

4. Querying projet status

The current project or a particular directory status can be queried by the following command :

 archipel status [file|directory]*

which gives the status of all the files in the current project, or you can also type

 archipel status .

to know what has changed in the current directory. Note that you can indicate any directory under Archipel control.

The status command ouputs a list of files prefixed by their tracking status:

• + for a file which is newly tracked
• - for a file that will not be tracked anymore
• for a file that is already tracked and will continue to be
• ~ for untracked files (they are not shown by default)

and content status:

• C for created file
• Cp for copied file
• Mv for moved file
• Rm for removed file
• M for modified file
• Nothing for an unmodified file

Created, copied and moved file all belong to files that are not found in the previous revision of the controlled project. These files were all created, copied or moved since last commit.

Removed files are files that cannot be found anymore in the current project, but were present when the project was last commited.

Modified and unmodified files are both present in the previous and current revisions of the project.

Status also allows:

• To include directories in the status (by default only files are shown)
• To decide which sets (new, changed, moved, etc. are considered as sets) have to be shown
• To use a specific filter to hide or show specific files or directories (like symlinks, or files ending with a specific suffix, etc.)

To get more information, you can type archipel help status.

5. Commiting changes

Once your project files are put under version control, you can commit changes that will represent the current state of your project (or at least, parts of it).

To commit changes, simply use the command

 archipel commit

which will commit all the changes made to the current project. Your default text editor (from the EDITOR environment variable) will then open, summarizing the changes and asking you to fill in a description. You can also commit changes locally with the following command

 archipel commit .

which will only commit changes made to the current directory. You can also specify any location

 archipel commit [location]

which will commit changes made only to the given location.

6. Getting project information

Once you commit changes to the repository, you might want to be able to refer to these changes (or change set) as a whole. To do so, you can use the head command:

 archipel head

which will return you the identifier (a 40 character string) identifying the set of changes you've just commited. This identifier also refers to the specific version of your project. When you will want to later retrieve this version (aka. check out), you will need this identifier.

7. Checking out versions

8. Publishing a release

Now you can read ArchipelAdvancedUsage