ARCV(1)                          User Commands                         ARCV(1)

NAME
       Arcv  -  arcv is a rsync-based, easy-to-use revision control tool which
       keeps intact users' files and directories

SYNOPSIS
       arcv [OPTIONS] [COMMAND]

       COMMAND:

       branch  BRANCH_FOLDER[:REVISION | RELEASE TAG]

              Branch off a revision

       changelog

              Display the history log since last release

       check

              Tell whether there are uncommitted modifications

       co  [REVISION | RELEASE TAG]

              Either update current source folder with head revision (no argu‐
              ments)  or  checkout  resp. the revision, release tag, file from
              head revision to the specified output folder

       destroy

              Put folder out of revision control and delete all  related  file
              from repositiory

       diff  [(REVISION | head | current)[vs(REVISION | RELEASE TAG)]]

              Make a diff with the specified revision using system diff tool

       export  [DIRECTORY]

              Export to a remote Git repo

       git  [(REVISION | head | current)[vs(REVISION | RELEASE TAG)]]

              Make a diff with the specified revision using git

       hash  [DIRECTORY]

              Display  the  hash signature for the head revision or the speci‐
              fied folder

       hook  [FILE]

              Create a release hook and lists the hook(s)

       list

              List the existing source folders stored in the repository

       log  [FILENAME]

              Show the revision log messages from most recent to  the  oldest,
              for the whole source or only the specified file.

       meld  [(REVISION | head | current)[vs(REVISION | RELEASE TAG)]]

              Make a diff with the specified revision using meld tool

       pub  [RELEASE TAG:REVISION]

              Create a new release tag

       push  <arg>

              Pushes  data  previously  fetched  to  the  URI  specified  with
              --source

       rel

              Show the release log messages from most recent to the oldest

       repo  [INFONAME]

              Display the specified information of the repository or all  when
              none specified

       rev

              Display the head revision number

       tarball  [REVISION | head]

              Create  a tarball for the current source folder or the specified
              revision

       OPTIONS:

       --cm-cfg =YAML path assignment

              Specifies a configuration parameter for the source in the repos‐
              itory

       --config

              Show the configuration file content

       --cycle =INTEGER[+]

              Specifies the size of the revision ring for circular revisions

       --debug

              Activate debug logs

       --fetch

              Update  the current source folder with the data fetched from the
              URI specified with --source and initiate check-in

       --fetch-only

              Create or update a source folder  that  will  contain  the  data
              fetched from the passed URI without committing the source folder

       --files

              Lists all the files used by the app (config, log etc)

       --fix

              Fix SHA hashcode

       --force

              Force a commit even when no change was detected

       --from =(REVISION | RELEASE_TAG)

              Specify  the  most  recent revision or release tag from which to
              start the operation

       --interval =INTEGER[+]

              Specifies the time interval in days, hours, minutes  or  seconds
              at which new revisions are allowed to be created

       --log =<arg>

              Show the log tail

       --no-cache, -U

              Force updating computed data instead of using cached one

       --revive

              Revive  file  from lastest version found in history when missing
              in head revision

       --rm

              Removes the created source after a direct fetch check-in

       --silent

              Silent mode

       --source =DIRECTORY | <URI>

              Source directory to checkout from the repository

       --to =(REVISION | RELEASE_TAG)

              Specify the oldest revision or release tag until which to  apply
              the operation

       --verbose, -V

              Verbose mode

       -F, --fmt ='adoc' | 'plain'

              Specifies the output format

       -X, --exclude =FILE PATTERNS

              Prevent certain file patterns to be checked in

       -f =FILENAME

              Configure the arcv operational config filename (permament)

       -l

              Dry check-in, listing only new/deleted/changed files

       -m, --message =STRING

              Commit log message

       -n

              Assume 'No' when prompted for confirmation

       -o, --output =DIRECTORY

              Output folder for checkouts or tarball exports

       -y

              Assume 'Yes' when prompted for confirmation

DESCRIPTION
       arcv  is a lightweight, safe, easy-to-use&learn revision control system
       which leaves the user's original source file tree  intact  and  ensures
       revisions integrity.

       Unless  some  traditional  well-known  revision control systems, 'arcv'
       fully respects the user's source folder integrity and  does  not  'pol‐
       lute' it with any additional files to achieve revision control. The re‐
       vision control data are centralized in a dedicated folder, the  reposi‐
       tory, which can be either a local directory or a mountpoint to a direc‐
       tory located on an external system.

       'arcv' only relies on standard system tools and there's  no  additional
       command set overlay needed to learn and use, e.g., for adding or remov‐
       ing files. For instance, to exclude and remove a file from the revision
       control, it is enough to remove the file from the system and commit the
       new revision. To add a new file, this file just needs to be present be‐
       fore commit.

       The architecture of 'arcv' is readable and open, which enables users to
       keep full control of the revisions and easily apply  common  corrective
       actions  without pain. E.g. if the user only recognizes somewhen after‐
       wards that a log message was incomplete or  incorrect,  it  can  simply
       modify  the  CHANGE_LOG file containing the message, without needing to
       execute multiple operations and the tooling skills coming along.

       Overall, the above few mentioned features enable 'arcv' to be of an ex‐
       treme  simplicity  of use at the reach of anybody, even non-developers.
       It enables an instant step-in and a drastic reduction of  the  learning
       curve  and  daily  time  overhead generally required to manage revision
       control.

       AUDIENCE

              arcv can be used by developers for the following 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 branch or
              another revision control system without polluting or unnecessar‐
              ily complexifying his historical record.

              It can also be used as general-purpose incremental backup tool.

       PLATFORMS

              Arcv  is  a  bash  script  primarly  developed  and tested under
              Ubuntu.  Because it features only minimalistic dependencies,  it
              is  deemed to run on most Linux systems and Cygwin-enhanced Win‐
              dows systems.

       DOCUMENTATION

              Please refer to the online page  https://slashetc.fr/en/develop‐
              ertoolsforlinux/arcv/arcv__documentation.html to access the full
              documentation:

              - Command usage with full examples

              - Architecture insight

              - Other pratical information

       SYSTEM DEPENDENCIES

              Arcv automatically handles dependencies toward  external  system
              packages,  i.e. it attempts to install all required system pack‐
              ages, e.g. meld or tar, when necessary.

COMMAND DETAILS
       branch BRANCH_FOLDER[:REVISION | RELEASE TAG]

              Branch off a revision.

       changelog

              Display the history log since last release

       check

              Tells whether there are uncommitted modifications. Return 0 when
              so, 1 otherwise.

       co [REVISION | RELEASE TAG]

              When used without argument, checks out all files of the head re‐
              vision. Any file of the current source may  get  overwritten  or
              removed.   Otherwise, checks out the specified revision, release
              tag or file from head revision to the specified output folder.

       destroy

              Put folder out of revision control and delete all  related  file
              from repositiory

       diff [(REVISION | head | current)[vs(REVISION | RELEASE TAG)]]

              Makes  a  diff with the specified revision using the system diff
              tool.  When no revision number is supplied, the head revision is
              considered  by  default.   Returns  0  when no difference is de‐
              tected, 1 otherwise.

       export [DIRECTORY]

              When used without argument, exports the head revision to the re‐
              mote  Git  repo.  When the path to a folder is supplied as argu‐
              ment, exports the content of that folder to the remote Git repo.
              This  latter  usage is suitable e.g. to export the clean release
              version of the source file tree, built at another location.  The
              URL of the remote Git repo shall be given in GITHUB.txt

       git [(REVISION | head | current)[vs(REVISION | RELEASE TAG)]]

              Makes a diff with the specified revision using git.  When no re‐
              vision number is supplied, the head revision  is  considered  by
              default.

       hash [DIRECTORY]

              Displays  the  hash signature of the head revision when no argu‐
              ment is supplied.  Otherwise, computes the  hash  signature  for
              the passed directory path

       hook [FILE]

              Without  arguments,  lists the defined hook(s).  Otherwise, cre‐
              ates a release hook with the passed executable that will be  run
              whenever  a  release tag is created. It will ensure that hook as
              the execution rights

       list

              Lists the existing source folders stored in the repository

       log [FILENAME]

              Without argument, shows the global commit history of the  source
              folder.   Otherwise,  shows the commit history for the specified
              file.  The global history is always shown from  most  recent  to
              the  oldest in batches of 5.  The file-specific history is shown
              from most recent to the oldest as a terminal  menu,  from  which
              the changes can be checked against head revision

       meld [(REVISION | head | current)[vs(REVISION | RELEASE TAG)]]

              Makes  a diff with the specified revision using meld tool.  When
              no revision number is supplied, the head revision is  considered
              by default.

       pub [RELEASE TAG:REVISION]

              When  no  argument is supplied, creates a new release by tagging
              the head revision with the  content  of  the  VERSION.txt  file.
              Then  it  prompts the user for the next version and updates VER‐
              SION.txt accordingly.

       push <arg>

              Pushes  data  previously  fetched  to  the  URI  specified  with
              --source.   The data is grabed from the current source folder or
              the head in the repository.

       rel

              Shows the release log messages from most recent to the oldest

       repo [INFONAME]

              Displays the specified information of the repository.  Supported
              values:   releases   latest-release-tag  latest-release-rev  ex‐
              clude-file exclusions src-dir rev-dir rev-hashfilepath rev-hash‐
              filename head-dir head-image-dir  git-repo size

       rev

              Displays the head revision number

       tarball [REVISION | head]

              Creates a tarball for the current source folder or the specified
              revision.  When used without argument, creates a tarball for the
              current source folder, i.e. the current working directory.  When
              a revision number is supplied as argument, creates a tarball for
              the  specified revision.  In both cases, the current working di‐
              rectory must be the root of the versioned folder.

OPTIONS DETAILS
       --cm-cfg YAML path assignment

              Specifies a configuration parameter for the source in the repos‐
              itory.

              The  parameter  will be stored in the YAML configuration associ‐
              ated with the source in the repository.

       --config

              Shows the configuration file content

       --cycle INTEGER[+]

              Specifies the size of the revision ring for circular  revisions,
              i.e.  the  number  of  revisions after which the revision number
              shall wrap around.

              When the cycle is a plain integer, the revision will wrap around
              starting from 0 again.

              Each  saved revision contains all data, and not only the differ‐
              ences.

              At wraparound, a new revision overwrites any previous one of the
              same number and thus gets lost.

              When the cycle is an integer number following by +, it addition‐
              ally initiates a parallel cycle backup source in the repository.
              Each  time is a cycle is completed, a new revision is created in
              the backup source duplicating the last cycle revision. The  name
              of  the cycle backup source is the original source to which -cy‐
              cle is appended and is managed automatically.

              A 0 cycle value means infinite (implicit default value).

              This option can only be specified at the initial commit.

       --debug

              Activate debug logs

       --fetch

              Update the current source folder with the data fetched from  the
              URI specified with --source and initiate check-in.

              Note  that  if  the URI was specified at very first commit (cre‐
              ation), it is not necessary to specify  --source  at  subsequent
              check-ins, as the data will be implicitly fetched from that ini‐
              tial URI.

              This operation is only allowed for a check-in.

       --fetch-only

              Creates or updates a source folder that will  contain  the  data
              fetched  from  the  passed  URI  without  committing  the source
              folder.

              This operation is only allowed at check-in, even though  no  ac‐
              tual check-in is initiated afterwards.

              This  function is provided for convenience for just generating a
              standalone MongoDB dump with dealing with any revision control.

       --files

              Lists the files used by the app, i.e.  the  configuration  file,
              the  log  file, the dependency system package installation cache
              file

       --fix

              This option enables to explicitly fix the  SHA  fingerprint  aka
              hash  code in case there's a mismatch between current source and
              the stored finger whilst no change was actually  detected.  This
              can  be  useful when the internal hash computation algorithm may
              change or could get anyhow broken because of an  untested  envi‐
              ronment  or an internal bug.  In any other case, this option has
              no effect.

       --force

              Forces a commit even when no change was detected

       --from (REVISION | RELEASE_TAG)

              Specifies the most recent revision or release tag from which  to
              start  the operation. A negative number N designates the Nth re‐
              vision behind the head. At the moment, this option is only rele‐
              vant for the history logs.

       --interval INTEGER[+]

              Specifies  the  time interval in days, hours, minutes or seconds
              at which new revisions are allowed to be created. For  instance,
              if the value is 1h or 3600s, an attempt to commit a new revision
              will be rejected an hour after the  last  commit.  A  margin  of
              +-10s is allowed.

              An  explicit  value of 0 means there is no restriction (implicit
              default).

              This option can only be specified at the initial commit  and  is
              usually used to enforce backup strategies.

       --log <arg>

              Show  the  log tail. By default, shows the last 40 lines and the
              number of lines specified as option value.

       --no-cache, -U

              Force updating computed data instead of using cached one

       --revive

              Revives a file from the lastest version found  in  history  when
              the  file is missing in head revision. This option is only valid
              in the scope of a checkout operation.

       --rm

              Removes the created source after a direct fetch check-in  A  new
              revision  can be created directly from an URI, without requiring
              an existing source folder, by fetching new data from the  speci‐
              fied  URI.  In this process, a matching source folder is created
              in the current directory. This option enables to  clean  up  the
              folder once the commit completed

       --silent

              Silent  mode.  Hides  messages  which are usually displayed even
              when verbose mode is not active.

       --source DIRECTORY | <URI>

              Either a source directory to checkout from the repository or  an
              URI  from  which to fetch the data from. Currently, only MongoDB
              URI are supported.

              The source folder to checkout can be specified with this  option
              instead  of resolving the source folder from the current working
              directory.

              When the value is an URI, it can also be used for  the  sake  of
              putting  under revision control the data fetched from the URI or
              create a new revision directly from the URI without requiring an
              existing source folder.

              A  Mongo  database content is fetched below the current workding
              directory, inside a source folder of the form "mongodb-<database
              name>@<database  host>-<database port>". The database content is
              written into a Gzipped archive  file  is  created  of  the  form
              "mongo-db-<database name>.gz".

              Afterwards,  an existing source folder can be used to create new
              revisions from the database simply by  passing  --fetch  to  the
              regular arcv commit command (arcv without argument), because the
              repository records the original fetch URI.

       --to (REVISION | RELEASE_TAG)

              Specifies the oldest revision or release tag until which to  ap‐
              ply the operation.  A negative number N designates the Nth revi‐
              sion behind the head. At the moment, this option is  only  rele‐
              vant for the history logs.

       --verbose, -V

              Verbose mode

       -F, --fmt 'adoc' | 'plain'

              Specifies the format of the output of a command. Possible values
              : "plain" for raw text without any color nor layout  formatting.
              "adoc" for AsciiDoc format.

              By  default when no format is specified, the text may be colored
              and the text blocks may be arranged to be more readable.

              At the moment, this option is only relevant for history logs and
              diffs. There is no effect if the format is not supported for the
              applied command

       -X, --exclude FILE PATTERNS

              Prevent certain file patterns to be checked in.  The  file  pat‐
              terns must be supplied as a coma-separated list of file patterns

       -f FILENAME

              Arcv operational configuration filename, if different of the de‐
              fault one coming along with the app, modified or not.

       -l

              Dry check-in, listing only new/deleted/changed files

       -m, --message STRING

              Log message

       -n

              Assume 'No' answer for any confirmation request

       -o, --output DIRECTORY

              Output folder for checkouts or tarball exports

       -y

              Assume 'Yes' answer for any confirmation request

EXAMPLES
              Please check the online cheatsheet https://slashetc.fr/en/devel‐
              opertoolsforlinux/arcv/arcv__cheatsheet.html

AUTHOR
       Written by Michel MEHL

REPORTING BUGS
       Report bugs to <michel.mehl@slashetc.fr>

COPYRIGHT
       Copyright  ©  2024-2026 Michel Mehl.  All rights reserved.  Tous droits
       réservés (France).

       License terms written down in file LICENSE.txt Les termes de la licence
       sont détaillés dans le fichier LICENSE.txt

Arcv 2.0.0                       October 2026                          ARCV(1)
