QuickStartGuide

+ +

This document describes how to use a client and a server for the first time after it has been installed. Server instructions are given after the client instructions.

All client instructions below assume you are within your workspace directory, not including the .cdv dir.

+ +

Creating a new project

+ +

Create a workspace directory and populate it with the files you want checked in. Within that directory: +

+cdv init
+cdv set user <username>
+cdv set repository <URL>
+cdv create <URL>
+cdv add ...
+cdv commit
+

Note: use of an email address as the username is recommended.

If you do not wish to collaborate with others or use a server for any other purpose, skip both setting repository and running create.

A repository URL has the following form: +

+cdv://<server>[:<port>]/<repository>
+

+ +

Check out an existing project

+ + +

+cdv init
+cdv set user <username>
+cdv set repository <URL>
+cdv update
+

+ +

Making changes

+ +

Codeville automatically detects when you have edited files in a client.

Rename or move files or directories: +

+cdv rename <source> <dest>
+

Delete files or directories: +

+cdv remove <files>
+

View your changes: +

+cdv diff [-r <changeset1> [-r <changeset2>]]
+

One -r flag will specify the change to diff from, a second the change to diff to. By default, the first change is the most recent change from the default repository (or the repository specied by -R). The second defaults to local, which is the current state of the workspace.

Show a more compact list of changes: +

+cdv status
+

When you are happy with your changes: +

+cdv commit
+

+ +

Reverting changes

+ +

Discard uncommitted file edits: +

+cdv revert <file>
+

Only changes to a file's contents can be reverted at this time. Name operations (add, delete, rename) are not yet reversible.

+ +

Taking branches

+ +

Branch using your current client state: +

+cdv create <URL2>
+cdv -R <URL2> commit
+

URL2 does not need to be on the same server as the URL you are branching from.

+ +

Merging branches

+ +

To merge URL2 into URL, from a client with URL set as the repository: +

+cdv update
+cdv -R <URL2> update
+(Resolve any name or merge conflicts)
+cdv commit
+

You may continue using branches after you have merged them. Codeville supports arbitrary branching, merging and remerging of any and all branches.

+ +

Resolving conflicts

+ +

File conflicts are presented in a similar fashion to CVS. Conflicting sections of the file will be marked with <<<<<<<, ======= and >>>>>>>.

Naming conflicts will result in mangled filenames. Look for files and directories which end with .nameconflict.local, .orphaned, .loop, etc. Sometimes there will be a file with a ".info" extension which contains where the file exists according to the update which caused the problem.

+ +

Other stuff

+ +

View history: +

+cdv history
+

This could use some explanation, but for now the change in parentheses is what brought this change into the repository. If you branch or merge, you may notice that many changes have the same one in parentheses.

+ +

Starting a server

+ +

Choose a directory to start the server in. Change into the directory and run: +

+cdvserver -i -f .
+

You will also need to create at least 1 account. Do this by running the cdvpasswd program in the server directory, for example: +

+cdvpasswd -f passwd add <username>
+

The special username "anonymous" is only allowed to do read operations on the repository.

Run cdvserver: +

+cdvserver -n -d -f <server directory>
+

You now have a running server. Running without -d will cause the server to fork off into the background and generally act more server-like. See the server reference for more details.

+ +

Ubuntu Init Script

+ +

Place the following in /etc/init.d/cdv and change the permissions to be world-executable using chmod 755 /etc/init.d/cdv -- note that this was based on the OpenBSD Secure Shell init script /etc/init.d/ssh.

+ +

+#! /bin/bash --
+set -e
+
+# /etc/init.d/cdv: start and stop the Codeville server
+
+oPATH="$PATH"
+
+PATH=/usr/X11R6/bin:/usr/bin:/usr/sbin:/bin:/sbin
+export PATH
+
+cdvserver="$(type -p cdvserver 2>/dev/null)"
+
+PATH="$oPATH"
+
+test :"$cdvserver" = :"" && exit 0
+
+test -x "$cdvserver" || exit 0
+( "$cdvserver" -h 2>&1 | grep -q Valid ) 2>/dev/null || exit 0
+
+if test -f /etc/default/cdv; then
+    . /etc/default/cdv
+fi
+
+. /lib/lsb/init-functions
+
+check_for_no_start() {
+    # forget it if we're trying to start, and /etc/cdv/cdvserver_not_to_be_run exists
+    if [ -e /etc/cdv/cdvserver_not_to_be_run ]; then
+        log_end_msg 0
+        log_warning_msg "Codeville server not in use (/etc/cdv/cdvserver_not_to_be_run)"
+        exit 0
+    fi
+}
+
+export PATH="${PATH:+$PATH:}/usr/sbin:/sbin"
+
+case "$1" in
+  start)
+        log_begin_msg "Starting Codeville server..."
+        check_for_no_start
+        start-stop-daemon --start --quiet --pidfile /var/run/cdvserver.pid --exec "$cdvserver" -- $CDVSERVER_OPTS || log_end_msg 1
+        log_end_msg 0
+        ;;
+  stop)
+        log_begin_msg "Stopping Codeville server..."
+        start-stop-daemon --stop --quiet --oknodo --pidfile /var/run/cdvserver.pid || log_end_msg 1
+        log_end_msg 0
+        ;;
+
+  restart)
+        log_begin_msg "Restarting Codeville server..."
+        start-stop-daemon --stop --quiet --oknodo --retry 30 --pidfile /var/run/cdvserver.pid
+        check_for_no_start
+        start-stop-daemon --start --quiet --pidfile /var/run/cdvserver.pid --exec "$cdvserver" -- $CDVSERVER_OPTS || log_end_msg 1
+        log_end_msg 0
+        ;;
+
+  *)
+        log_success_msg "Usage: /etc/init.d/cdv {start|stop|restart}"
+        exit 1
+esac
+
+exit 0
+

+ +

Miscellaneous notes

+ +

Performance should be reasonable, there are still more optimizations to be done. For now, you will get better performance by updating after each commit.

All files are assumed to be text. That is, Codeville will attempt to merge them. Support for binaries and non-ascii encoded files will happen before 1.0.

At this point the repository format should be stable enough that there will always be an upgrade path for the servers.

+ + +

Codeville commands

+ + +

Options

+ +

-p, --path: <path> to client
+
-R, --repository: <repository> for this operation
+
-u, --user: <user> as whom to perform this operation
+
-V, --version: Print version information
+

+ +

Subcommands

+ + +

+add <files>
+

Add new files to the repository. All files must be added before they will be part of the version control system.
+

+commit [-b] [-m <comment>|-M <comment-file>] [-D <date>] [-n]
+

Commits all changes made to the repository since the last commit. A comment is required for every commit. It may either be supplied via the -m option for simple comments or if the -m option is omitted, whatever editor is specified in the EDITOR environment variable will be launched. If no editor is specified, vi is the default in all unixy environments (including OS X and cygwin) and Notepad is the default in Windows. In the editor, a comment may be added at the top, and file changes which the user does not wish to have in a given changeset can be removed by deleting them from the "### files" list at the bottom (although merging cannot be avoided through deleting things from the "### merge files" list). Every commit creates a changeset. If there are changes since the last update, files will be merged. In the event of unresolved conflicts, the user will be prompted to resolve them.
+

-b, --backup: Forces commit to not make a new changeset. This will commit changes which have already been committed locally via -n (or as a result of having multiple repositories involved), but will not create a new changeset for existing file modifications. This is especially needed for committing to back-up servers (servers started with -b) as it is the only way to commit changes to a back-up server. This is not the recommended way to commit changes to normal servers. In general, if one wishes to commit changes committed offline without committing new changes, one should commit and changeset with all the files in the "### files" list removed.
+
-D, --date: YYYY/MM/DD HH:MM:SS TZ indicating changeset creation time
+
-m, --message: Use message as the commit message
+
-M, --message-file: Get commit message from file
+
-n, --no-network: is used to commit changes off-line. Changes committed off-line can still be used with all commands, but are not visible to other users until an on-line commit is done.
+

+construct <changeset>
+

Recreates the repository at the given changeset.
+

+create <repository name>
+

Creates a new repository with the appropriate name.
+

+describe [-x|-d] [-s] <changeset>
+

Gives the description of the changeset including the long name of the change, the user who made the change, that date it was made, the comment, the relation it has to other changesets, and what files were modified and in what manner they were modified (i.e. added, modified, renamed, or deleted).
+

-d, --diff: does a diff
+
-x, --xml: displays an XML version of the output. This is not compatible with displaying a diff. This can only be used with parenthesized changesets from the file history. It's sort of a hack right now, really.
+

+destroy <repository>
+

Destroys a repository. The opposite of create.
+

+diff [-r <changeset> [-r <changeset>] ] [<files>]
+

Does a diff between different versions of each of given files. If no files are specified, all relevant files are shown. The first -r option indicates which changeset the diff should be from, the second which it should be to. If no changesets are specified, it shows the difference between the last known state of the repository and the current client state.
+

+edit <files>
+

Enables editting a file. When not in edit-mode, this is unnecessary.
+

+heads
+

Lists the root nodes in the graph of changesets.
+

+history [-h <changeset>] [-c <count>] [-s <skip count>] [-v] [<files>]
+

Gives the history of the repository or of the files specified. Specifically, it lists all relevant change sets by short name, user, date, and comment in most recent first order.
+

-c, --count: print only the specified number of changes.
+
-h, --head: print the history starting at the given changeset.
+
-s, --skip: skips the first skip count changes.
+
-v, --verbose: causes it to print the changes verbosely which includes additional information about each changeset which affected the files.
+

+init
+

Initialize a new client with the current directory as the root. Specify a directory other than current one by using the top level -p switch.
+

+is_ancestor <changeset1> <changeset2>
+

Tells whether or not changeset1 is an ancestor of changeset2. Note that it is possible for neither changeset to be an ancestor of the other.
+

+last-modified <file>
+

Returns the last changeset which modified a given file.
+

+list-repos
+

Lists all the repositories on the same server as the repository you are in.
+

+password
+

Change your password.
+

+print_dag [-h <changeset>] [-h <changeset>] [...] <file>
+

Prints the directed acyclic graph which shows the changesets which have been applied to a file and their relationships.
+
Changesets specified with -h are treated as head nodes for the graph (i.e. later changesets are excluded).
+

+print_history [<changeset>]
+

Prints the directed acylcic graph of the the entire history. Starts at the given changeset, if provided.
+

+rebuild
+

Recreates all of the metadata from the static history. This should generally only be done when instructed to by software upgrade instructions.
+

+remove <files>
+

Deletes files from the repository.
+

+rename <file> <newname>
+

Moves or renames files.
+

+revert [-a] <files>
+

Reverts any local changes to the file. At this time only changes to the content of the file can be reverted. The ability to revert adds, deletes, and renames will be coming in the future.
+
There is a subtle difference in the definition of revert from what you might expect. It does not guarantee that it will restore the file to some previous state. For example, if you are in the middle of a merge and call revert on a file, it will be regenerated by running the merge. If the file were modified prior to running the merge update, the file contents will now be different from anytime in the past.
+
Revert should be thought of as throwing away uncommitted changes.
+

-a, --unmodified: indicates files should only be reverted if they have not been modified. Basically unmarks them as open for edit.
+

+set <variable> <value>
+

Sets a Codeville variable to a given value.
+

+show-vars
+

Show a list of all Codeville variables and what they are set to.
+

+status [-v]
+

Shows changes not yet committed to the repository in brief.
+

-v, --verbose: A more verbose status which includes mention of files which are in the directory space, but not in the repository and files missing from the directory space.
+

+unset <variable>
+

Removes a Codeville variable so that it no longer has any setting.
+

+update [-d]
+

Gets all changes made to the repository since the last time you did an update. Files will be merged as necessary. In the event of unresolved conflicts, the user will be asked to resolve them.
+

-d, --dont-merge: Pull in changesets but do not merge them. Has no effect on the workspace state. This allows a user to browse and diff changesets without having to merge.
+

Specifying files:

+ +

General Notes

+ +

Files can be specified using bash-style wildcards on any platform. In addition, '...' behaves like a find command, expanding all files and directories within subdirectories.

All printed graphs are output in a format intended to be run through the graphviz "dot" tool.

Using tcsh as the startup shell under cygwin appears to result in the Python password command hanging, so it is incompatible with Codeville and there's not a thing we can do about it.

+ + +

Creating a new project

Check out an existing project

Making changes

Reverting changes

Taking branches

Merging branches

Resolving conflicts

Other stuff

Starting a server

Ubuntu Init Script

Miscellaneous notes

ClientReference

Codeville commands

Options

Subcommands

General Notes

ToDoList

The Magic TODO list

larger features

smaller stuff

ServerReference

Running a Server

Unix and OS X

Config file options

Files and Directories

Control options

General Notes

Windows

Config File