\input texinfo
@setfilename chii.info
@settitle Chii Manual

@titlepage
@title Chii
@subtitle Lightweight version control system
@end titlepage

@contents

@ifnottex
@node Top
@top Chii
@end ifnottex

@menu
* Overview::         Why bother?
* Commands::         What can I do with it?
* Implementation::   What's happening behind my back?
@end menu

@c ----------------------------------------------------------------------
@node Overview
@chapter Overview of Chii

Chii is a lightweight version control system.  The goal was to create
a minimalistic version control system suitable for small to medium
sized projects that do not require full production grade source
control software.

Main features include:

@itemize @bullet
@item
No separate server - no extra daemons taking up resources when you are
not using them.
@item
Minimal setup - no need to tweak configuration files or environment
variables, first @code{commit} command creates the repository.
@item
Minimal cleanup - delete a single directory when previous versions
are no longer needed.
@item
Flexible - run any shell command directly on any version of any file.
@end itemize

These features alone were the motivation for creating yet another
source control system.  All other features are intentionally not
implemented, notably:

@itemize @bullet
@item Multi-user support.
@item Permissions/protections.
@item Branching.
@item Space efficient repository.
@end itemize

If there are any other feature that can be removed, they would have
been removed already @samp{^_^;}


@c ----------------------------------------------------------------------
@node Commands
@chapter Commands

Chii contains only one special command, all other commands are handled
generically.

@menu
* commit::
* generic commands::
@end menu

@node commit
@section @code{commit} - snapshot source tree

@code{chii commit}

Create a snapshot of the current source tree in the repository
(@xref{repository}).  If a repository does not yet exist, the first
@code{commit} creates it, so the first @code{commit} should be done in
the root directory of the source tree.

Chii will compare every file and directory with the latest version
found in the repository, and append to changelog the list of changes
(@xref{changelog}).  Note that a copy of every file in the source tree
is included with every snapshot regardless of whether they changed or
not, so versions are not dependent on each other.

Chii assumes all directories have the right read/execute permissions.
If this is not true, the behavior is undefined.  Chii will always
create directories with 0750 permission.  Permission on all files are
preserved.

@node generic commands
@section Generic commands

@code{chii <command> <options>}

For all commands other than @code{commit}, Chii will expand
@code{<options>} to file names in the repository, then pass the
expanded arguments to @code{<command>}.  Every argument containing
@samp{#} is subject for expansion.  The basic syntax for naming file
versions is:

@code{<filename>#<version>}

@itemize @bullet
@item
@code{<filename>} specifies the name of file, with relative paths
expanded.  Use @samp{*} to match all files in repository directory
(files only, directories not included).
@samp{...} to match all files in repository directory and
subdirectories (files only).
@item
@code{<version>} names a file version, which is a date string in the
form of @code{yyyy-mm-dd-HH-MM-SS}.  Any part of @code{HH-MM-SS} may
be dropped, in which case all versions with the same prefix will be
matched.
@item
In place of date strings, you can specify a single integer to name
relative versions, with @samp{1} being the first (oldest) version in
repository.  Use negative numbers to count backwards, @samp{-1} is the
newest version.
@item
@code{<filename>#} (missing version) selects the last version in
repository.
@item
@code{#<version>} (missing filename) names a file in the root
directory of the repository.  Usually you would want to do this with
@code{#changelog}.  To operate on an entire version subdirectory with
version expansion, use @code{.#<version>}.
@item
To specify a literal @samp{#} in the argument, prefix it with a
@samp{\}.  Chii will only expand arguments containing a single
unescaped @samp{#}.
@end itemize

Depending on your shell, you may need to escape @samp{*} character in
the arguments.  Note that using @samp{*} or @samp{...} may cause a
single argument to be expanded to multiple arguments.


@c ----------------------------------------------------------------------
@node Implementation
@chapter Implementation details

@menu
* repository::
* changelog::
@end menu

@node repository
@section Repository structure

@verbatim
<parent directories>
 \-- <source root>
 |    \-- subdir1
 |        \-- subdir2
 |
 \-- chii_repository
      \-- changelog
      \-- <yyyy-mm-dd-HH-MM-SS>
          \-- subdir1
              \-- subdir2
                  ...
@end verbatim

Each snapshot of the original source directory is stored in a
subdirectory under the repository root.  The root directory of the
snapshot is a date string, which names the snapshot version.

For relative version names, the directories are sorted alphabetically,
and the first directory becomes version 1, next is version 2, and so
forth.  Actual timestamp of the directories are ignored.

@node changelog
@section Changelog format

@verbatim
<yyyy-mm-dd-HH-MM-SS>
   <file> <action>
   ...
@end verbatim

Each @code{commit} causes an entry to be written to the changelog
(stored in the root directory of the repository).  Each unindented
line specifies the change version, and each indented line specifies
which file changed.

@bye