From AuroraUX

Monotone HowTo

Monotone is a distributed version control system with tightly integrated cryptographic integrity and authenticity checks. This howto is not meant to be an exhaustive set of documentation on monotone (see their huge set of manuals and wiki for that), but merely a means to bootstrap AUX developers.

I Just want the Code now to have a look!

WARNING: We highly recommend you read the rest of this documentation if you intend to do development on AuroraUX system!

• Workspace;

  $ mkdir -p ~/lab/auroraux/project

• Hydra Package Manager.

  $ mtn clone auroraux.org org.auroraux.hydra.primary

• AuroraUX Desktop Environment Suit - X11, Window Manager, Etc..

  $ mtn clone auroraux.org org.auroraux.supernova.primary

• AuroraUX Base System - Kernel, System Libraries, Etc..

  $ mtn clone auroraux.org org.auroraux.singularity.primary

• Non-Essential System Components - Build-Chains, Etc..

  $ mtn clone auroraux.org org.auroraux.universe.primary

• AuroraUX Installation Suit.

  $ mtn clone auroraux.org org.auroraux.nebula.primary

Creating a Personal Monotone Identity

Before using monotone, each developer must generate an 'identity' key, which uniquely identifies that developer to monotone. Your 'identity' can be any unique string. Using an existing email address is often a good choice (ie ).

  $ mtn genkey 

As a convenience, you may want to inform ssh-agent of your monotone 'identity' key. This avoids having to enter your password each time.

  $ mtn ssh_agent_export ~/.ssh/id_monotone
  $ chmod 600 ~/.ssh/id_monotone

Now, when you first log in, you need only add your monotone 'identity' key to ssh-agent.

  $ ssh-agent /bin/bash
  $ ssh-add ~/.ssh/id_monotone

Tracking AuroraUX Development

If you do not have write permission and wish to contribute, then ...

If you have any changes you want to make to the main AuroraUX branch, you can bundle them up with mtn diff - mail that to a AuroraUX developer or the $PROJECT_NAME-commit mailing list at auroraux.org. The changes will be reviewed and applied and then pushed onto the org.auroraux.$PROJECT_NAME.primary repository for everyone to access. Over time, if you want commit privileges on the org.auroraux.$PROJECT_NAME.primary repository, that can be arranged - see below for more details.

Creating a Personal Monotone Workspace

Directory Structure

• Work Area:

  $ mkdir -p ~/lab/auroraux/project/{supernova,hydra,singularity,universe,nebula}
  $ mkdir ~/monotone_db

Database

To create our own personal monotone database for all our project's;

• Database:

  $ mtn db init --db=~/monotone_db/aurorauxdb.mtn

PROJECT SOURCE - {Supernova,Hydra,Singularity,Universe,Nebula}

• Set Our Project to Work on (Example for Project Supernova):

  $ export PROJECT_NAME=supernova

• Work Area:

  $ cd ~/lab/auroraux/project/$PROJECT_NAME

• Pull in the source:

First we must pull from the formal project database into our database;

  $ mtn --db=~/monotone_db/aurorauxdb.mtn pull auroraux.org "org.auroraux.$PROJECT_NAME.primary"

Our 'personal' database now holds a copy of the project's 'formal' monotone database. We now need create, from our 'personal' database, the actual project directories and files, within our filesystem. This is done via the monotone 'checkout' command.

  $ mtn --db=~/monotone_db/aurorauxdb.mtn --branch=org.auroraux.$PROJECT_NAME.primary  checkout .

Our project is now set up and ready for everyday development work.

Joining a Project

Security

Inform one of the project lead developers of your wish to join, and send him your public monotone 'identity' key, which is generated via,

  $ mtn --db=~/monotone_db/aurorauxdb.mtn pubkey  >~/joe.pubkey

Providing this key allows the lead developer to set your read/write permissions.

Committing Work

File Modifications

Common activities include:

  $ mtn  add xyz.txt                         -- add a file, wildcards are allowed
  $ mtn  add --recursive  a_new_directory    -- add a directory recursively

  $ mtn  drop xyz.txt                        -- remove a file or directory

  $ mtn  mv  foo.txt bar.txt                 -- rename a file or directory

Sync and Commit

To fetch other developer modifications:

  $ cd ~/lab/auroraux/project/$PROJECT_NAME

> Note this *well* ! :
  $ mtn help sync
>> For the *current* default branch:
  $ mtn sync
>> *OR*, All branches in your db file:
  $ mtn sync auroraux.org '*' 

  $ mtn update

To commit your own changes:

  $ cd ~/lab/auroraux/project/$PROJECT_NAME

  $ mtn commit -m "Changed Foo to Bar"
  $ mtn sync

Monotone CheatSheet

• mtn sync primary.auroraux.org --branch=$PROJECT_NAME

this pulls the latest changes from the repository into your database, and pushes your latest already-committed changes from your database into the repository.

• mtn commit

this commits the local changes in your monotone workspace into your local database, signing the new revision with your nym key. Please be sure to update the CHANGES file with a bullet point for each substantial change above the most recent release. On the other hand, if you are making a new release, include a date and version line in CHANGES, update VERSION, as well as the version numbers in doc/web/download.html.

• mtn status

this summarizes what files have changed in the monotone workspace

• mtn diff

this details what has changed in the monotone workspace

• mtn add $filename

this schedules a file for inclusion in the database on next commit

• mtn drop $filename

this schedules a file for removal from the database on next commit

• mtn revert $path

this undoes any local changes for the given path (which can be a file or directory)

• mtn update

this pulls the latest changes from the local database into your workspace

• mtn log $filename

this views the change history of the given file

• mtn heads

this lists the revision ids of the unmerged paths on the current branch ("$PORJECT_NAME")

• mtn tag $revision $tagname

this cryptographically tags the given revision id with the specified tag (e.g. "mtn tag a8af872 hydra-0.912b"). note that the revision can be a short substring of the full revision id - "a8af872" instead of "a8af872ccdc00b5995dd1c05f15d8912804bba99"

• mtn db kill_tag_locally $tagname

if the tag has not been pushed out onto any other databases, this will remove the cryptographic certificate that associates the given tag with a revision. This effectively allows you to move a tag (circa cvs tag -F)