Arcv
Documentation
Manpage

Arcv

arcv

In a nutshell

arcv is a minimalistic revision control system which strives to adhere to the following principles:

  • Inviolability of the original source file tree

    • Strict separation between the source and the revision control data

    • Source file tree is not impacted and modified by revision control data

    • The user keeps full control of its files and how they can be backed up, shared, or exported to other systems

  • Simplicity of use

    • Enabling instant step-in, no knowledge required

    • Within the reach of non-developers

    • No complex branching and merging system

  • Simplicity of architecture

    • A central storage (repository), decoupled of the source files, is used to track different file revisions

    • Simple file copies and file difference checking

    • Full transparent and understandable file organization

    • No exotic encoding and Ids

    • Reliance on existing, proven-in-use standard system tools like rsync, diff, ls, sha256sum

arcv is aimed at the following audience and purposes:

  • Individual developers or single person-lead projects

  • Early development stages of projects, prototyping

  • Individual, well-targeted, independent development lines or branches, which can be easily integrated into the main revision control system without polluting or unnecessarily complexifying his historical record.

What arcv is not aimed to:

  • Large projects, requiring collaborative works over Internet.

  • Shared projects, requiring multiple branches and merges

Installation

As Debian system package (requires root rights)
wget https://slashetc.fr/download/arcv_1.0-0_amd64.deb
sudo dpkg -i arcv_1.0-0_amd64.deb
As free installation
# Sample, select the target installation folder and desired version
wget https://slashetc.fr/download/arcv.0-0.zip
unzip arcv_1.0-0.zip

The following table lists all the available versions. You can also click on the link to download instead of using wget:

Platform Debian Package Zip Creation time

Linux

arcv_1.0-0_amd64.deb

arcv_1.0-0.zip

2026-05-20

Architecture

Overview

A standalone folder is used as repository to store the successive changes applied to a reference source folder. There’s a 1-to-1 relation between the source and the repository, there can’t be any other image.

Successive changes are saved inside the repository. The operation that consists in saving changes at an instant time is called 'check-in'. Saving changes is also called committing changes. A revision number is associated to each committed changes (aka a commit).

The state of the source folder or any file inside it can be restored according to the state it has at a given commit identified by its revision number.

Refernece source code folder Action Repository folder state

📁 testapp

check-in ➡

📁 Archive

📁 testapp

check-out ⬅

📁 Archive

Revision numbers

A revision number identifies the state of the whole source folder and all files contained therein. There’s no individual numbers managed for each file. However, the revision where a file was lastly modified can be retrieved.

Repository structure

This explains how the repository is structured for saving the changes for each source folder/project under revision control.

Archive folders

When a source folder is put under revision (when committed first time), a dedicated archive folder dedicated to it is created with the .archive extension.

Each revision (committed changes) is saved inside a dedicated subfolder with the .archive<revision> extension.

Eventually, the folder structure where the changes are committed are the same as the original source folder, whereby the root folder name is therefore the same as the root source folder.

The following table illustrates what happens:

Time Source code folder Action New revision Repository folder state

↧

📁 testapp

📁 Archive

📁 testapp

➡

0

📁 Archive
      📁 testapp.archive
            📁 testapp.archive0
                  📁 testapp

📁 testapp

➡

1

📁 Archive
      📁 testapp.archive
            📁 testapp.archive0
                  📁 testapp
            📁 testapp.archive1
                  📁 testapp

Archive files

Upon check-in and the creation of a new revision, an archive file is created to hold a copy of any source file that changed since the last committed revision.

This is illustrated by the following example, which shows the repository state on the following use scenario:

  • 'testapp' , a project folder containing 3 files, resp. file1.txt, file2.txt and file3.txt, is put under revision the first time.

  • Then, the file2.txt is modified and the source folder is checked in.

Time Source code folder Action New revision Repository folder state

↧

📁 testapp

📁 Archive

📁 testapp
      📄 file1.txt
      📄 file2.txt
      📄 file3.txt

➡

0

📁 Archive
      📁 testapp.archive
            📁 testapp.archive0
                  📁 testapp
                        📄 file1.txt
                        📄 file2.txt
                        📄 file3.txt

📁 testapp

➡

1

📁 Archive
      📁 testapp.archive
            📁 testapp.archive0
                  📁 testapp
                        📄 file1.txt
                        📄 file2.txt
                        📄 file3.txt
            📁 testapp.archive1
                  📁 testapp
                        📄 file2.txt

Revision control-specific files

Besides the actual user files, additional folders and files are managed for the sake of the revision control and efficient check-in and check-out operations.

In the top archive folder of the project:

  • ROOT: this file stores the absolute path of the source folder under revision control. The path is the local path on the host where the repository is located.

  • head: this folder contains a full copy of the head revision. It reflects the latest state of all files under revision control as they were comitted at last.

  • head/REV: this file stores the head revision number. It is necessarily the highest revision number.

  • dropped: a modified file, which is checked out without being checked-in beforehand, is saved in that folder. It is named is formatted .#modified.<initial file revision>.<file name>

In the revision sub folder of the archive folder:

  • CHANGE_LOG: this file stores the change log entered at the time the source folder was committed.

  • .arcv_sha256_<source folder name>: this file stores the SHA256 digest computed over the file list of the source folder under revision control at the time of the check-in. The file list is the output of ls, including access rights and date time information.

Time Source code folder Action New revision Repository folder state

↧

📁 testapp

📁 Archive

📁 testapp

➡

0

📁 Archive
      📁 testapp.archive
            📄 ROOT
            📁 head
                  📄 REV
                  📁 testapp
            📁 dropped
            📁 testapp.archive0
                  📄 CHANGE_LOG
                  📄 ._arcv_sha256_testapp
                  📁 testapp

Example of real repository

Example of real repository

Restrictions

  • Symbolic links are under not revision control

Configuration

Overview

Arcv first reads a main configuration file located in the .config folder of the user’s home directory.

This file is actually mainly used to give the path to the actual operational configuration as entry point.

This indirection is set up that way to give the user the freedom and ability to:

  • use a shared, base configuration available over the LAN, but accessed via a different path depending on how the remote folder containing the config is actually mounted locally (typically, via NFS).

  • manage the revision-control of the configuration file at a more suitable location and at a central place on the LAN

  • override individual parameters on the local machine, e.g. user name and email

Location

The main configuration file is located in the .config folder of the user’s home directory (letter case is relevant):

$HOME/.config/Arcv/arcv.yml

If this file does not exist, it will be copied from the default configuration file coming along the release in the sumo’s installation directory.

If the user’s configuration file cannot be read for any reason, the default one is used.

The default operational configuration which is created is $HOME/arcv.yml. If this file is moved, the main configuration file has to be adapted to reflect the path change.

Alternatively, the -f option can be used once to specify which operational configuration files is to be used, whereby the tool will automatically adapt the main configuration file to reflect the new path.

Main configuration

Table 1. Main configuration parameters
Option Description

arcv config

the path to the operational configuration, relatively to the HOME directory where arcv is run on the local machine
Sample main configuration
arcv config: riffian/Data/Data/admin/linux/configs/arcv.yml

Operational configuration

Table 2. Operational configuration parameters
Option Description

host

name of the host on the LAN where the repository is located

storage

path to the repository on 'host'

storage-via-nfs

path to the repository when it is accessed via NFS

copy-cmd

the command to use to copy files

copy-args

the copy command to use to copy files

git-diff-args

the git diff arguments if git is used for diffing using '--diff' option

user-name

user name when exporting to GitHub

user-email

user email when exporting to GitHub
Sample operation configuration
host: riffian
storage: "/home/michel/Data/Archive"
storage-via-nfs: "/home/michel/riffian/Data/Archive"
copy-cmd: "rsync"
copy-args: "-a -X --progress --modify-window=1"
git-diff-args: "-w --word-diff=plain --word-diff-regex=."
user-name: Michel MEHL
user-email: michel.mehl@slashetc.fr

Commands

General usage

The exhaustive command usage and accepted arguments are documented in the manpages and can be checked on the command line by typing :

arcv -h

or

av -h

The commands are always to be considered in the context of the current working directory where they are executed. To perform an operation on a file tree under revision control, the user must change its current directory to the top directory of that file tree.

If the current working is not the top directory but a subdir below it, arcv will attempt to go upward in the file tree hierarchy and apply the operation on the first directory for which revision control data is available in the repository.

Command alias

For the sake of convenience for frequent tasks, the following short-named alias scripts are available:

Alias Equivalent command Description

av

arcv

Runs arcv passing on arguments

avl

arcv log --verbose

Show the revision logs , long format, i.e. showing the changed files for each revision

avd

arcv diff

Standard line-by-line diff with the head revision

avc

arcv check --verbose

Tells whether there are changed compared with the head revision. Returns 0 if no change, 1 otherwise.

Check-in

Initiate revision control

A folder is put under revision control by changing directory to it and simply calling arcv without argument.

Usage for Initiate a revision control
arcv
Sample command
arcv
Example of putting a source folder under revision control

For the sake of the test, an existing repository of riffian is used and is accessed via NFS. A new source folder test-arcv/test-project is created with 2 files file_A.txt and file_B.txt. The folder is put under version control, specifying the actual repositiory Then, the following checks are done: current revision number, short and long revision log. Eventually, arcv is called as check-in request to check no change is indeed detected.

arcv sshot init 1
Figure 1. Example of putting a source folder under revision control

Add files

arcv will detect any new file when attempting to check in simply calling arcv without argument.

Usage for Check-in a new file
arcv
Sample command
arcv
Example of check-in of a new file

An existing remote repository is used via NFS. A new file is created and it is checked that the "check" command detects it. Then the file is checked in. Before and after check-in, the folder is checked for modification using 'check' command. At the end, the following is checked : current revision number, revision log

arcv sshot addfiles 1
Figure 2. Example of check-in of a new file

Remove files

arcv will detect any missing file and remove them when attempting to check in simply calling arcv without argument.

Usage for Check-in a file for deletion
arcv
Sample command
arcv
Example of check-in a new file for deletion

An existing remote repository is used via NFS. file_A.txt is removed and the folder is checked in. Before and after check-in, the folder is checked for modification using 'check' command. At the end, the following is checked : current revision number, revision log

arcv sshot removefiles 1
Figure 3. Example of check-in a new file for deletion

Modify files

arcv will detect any modified file when attempting to check in simply calling arcv without argument.

Usage for Check-in a modified file
arcv
Sample command
arcv
Example of check-in of a modified file

A line is added to the previously added report "test_report.txt" Before and after check-in, the folder is checked for modification using 'check' command. During check-in, a menu is proposed to select the modified file. When pressing <enter>, the changes can be checked with meld tool. At the end, the following is checked : current revision number, revision log

arcv sshot modifyfiles 1
Figure 4. Example of check-in of a modified file

Check-out

Check-out a specific revision

By default, the name of the checked out folder will be the original source folder name suffixed with -rev<revision>.

The parent output folder where the revision will checked out can be specified with the -o option, otherwise the user will be asked for it.

Usage for Checkout a revision
arcv
Sample command
av co 0 -o /tmp || _exit -1 "Error: check out failed"
Example of check-out of a revision

The previously created folder "test-project" is checked out in /tmp. The following is checked: folder content and file contents. Before and after check-out, the folder is checked for not having being changed.

arcv sshot checkoutrev 1
Figure 5. Example of check-out of a revision

Restoring a modified file

Usage for Checkout/restore a specific file after modification
arcv
Sample command
arcv co "test_report.txt"
Example of check-out of a modified file

The previously added file "test_report.txt" is changed. It is then restored from the head revision. An attempt to restore it a second time is done to check that file is up-to-date. Before and after, the file content is checked.

arcv sshot checkoutfile 1
Figure 6. Example of check-out of a modified file

Logging

The log file is the following:

$HOME/.local/arcv/log.txt

At the moment, it will be endless growing and survive over successive runs.

Lifecycle

Configuration management

The configuration management of the original software is managed on a non-disclosed server with arcv.

The clean release packages and the release source code files are available on GitHub at https://github.com/michelm33/arcv

Bug tracking

Reported bugs are tracked via the GitHub page https://github.com/michelm33/arcv

External platforms

GitHub

https://github.com/michelm33/arcv

StackOverflow

https://stackoverflow.com/users/32241714/michel-mehl

Patreon

https://www.patreon.com/14930736/join

PayPal

https://www.paypal.com/donate/?hosted_button_id=G2QSV9ZD4EB4A

Donating and gifts

How you can support this work and how to claim your gifts is reported on this page: Donate & Gifts online page.

Thanks

Probably this list may be completed over time, sorry if I missed anyone!