.. _cli:

################
Command Line Use
################

.. admonition:: Tip
   :class: tip

   This section is of interest to those who are proficient at Linux. This section can be skipped if you are an end-user.

When versioning for a folder is enabled, there will be a (hidden) ".archive"
subfolder that will contain versions with a colon (":")
and a numbered suffix, with the number increasing for later versions.

..
.. image:: cli.png

.. raw:: html
	 
   <p style="text-align: center; margin-top: -20px;"><strong><em>Contents of an example &quot;.archive&quot; folder.</em></strong></p>

For reasons of safety, these file versions are "immutable"
to prevent accidental deletion. If you need to manually remove
these files or the entirety of a ".archive" folder, you will need to do so
as the linux root account using either
`"sudo" <https://wiki.debian.org/sudo>`_ or
`"su" <https://manpages.debian.org/bookworm/util-linux/su.1.en.html>`_,
along with the "rm" command.

*******************
Configuration Files
*******************
The following are essential files used by repliversion.

* **/etc/repliversion/dirs.txt:** This file contains a list of absolute folder paths that are being versioned. Since repliversion versions any subfolders for a given folder being versioned, you cannot have a path that is already versioned by another entry.

* **.archive/version.xml:** In any folder being versioned, this file contains the per-folder "prune", "skip", and "repo" directives.

* **/etc/repliversion/version.xml:** This is the global settings file for "prune", "skip", and "repo" directives.

* **/etc/repliversion/repos.xml:** This file contains "access tokens" for various repositories. Note that for security considerations this file is only viewable by the system root account. This file might contain multiple "**<repo...**" XML elements, each with the attributes: **git_url** and **access_token**.

*************************
Directives in version.xml
*************************
* **prune:** Expressed with one or more "**<prune...**" XML elements, having the following attributes: **filename**, **max_versions**, **max_age**, **max_size**, and **frequency**. See the :ref:`"Prune Directives" <prune>` section for more info on what these attributes govern.

* **skip:** Expressed with one or more "**<skip...**" XML elements, having the following attributes: **path**, and **comment**. See the :ref:`"Skip Directives" <skip>` section for more info on what these attributes govern.

* **repo:** Expressed with a **single** "**<repo...**" XML element, having the following attributes: **git_url**, **type** ("gitlab" or "github"), **owner**, and **folder_base** ("watched" or "root"). See the :ref:`"Git Directives" <git>` section for more info on what these attributes pertain to.

After you manually edit any directives in version.xml (be it the global
"/etc/repliversion/version.xml" or a ".archive/version.xml"...), you will
need to restart the repliversion service.

.. code-block:: bash

  systemctl restart repliversion

This is a privileged operation that you will need to perform with
`"sudo" <https://wiki.debian.org/sudo>`_ or
`"su" <https://manpages.debian.org/bookworm/util-linux/su.1.en.html>`_.

.. admonition:: Tip
   :class: tip

   When editing "version.xml" manually (as opposed to using the Dolphin file manager context menu for editing per-folder or global directives...), you will probably want to check the repliversion log ("/var/log/repliversion.log") to confirm that the service restarted without errors, to make sure no mistakes were made.

.. note::
   The need to restart the repliversion service after editing "version.xml" might be removed in a future version of repliversion; check out the :ref:`Wishlist <wishlist>`.

.. _commands:

********
Commands
********

The following commands can be invoked from a Linux command shell.

.. _repliversion:

.. code-block:: bash

  repliversion [+|-]<folder_path>

Specify a folder to be versioned. A plus prefix indicates a folder to be
versioned; a minus prefix indicates a folder to no longer be versioned (the folder's ".archive" folder with its versions will still remain...)
This is analogous to the Dolphin file manager context menu commands
"Actions", "Enable Versioning..."|"Disable Versioning..."
If you are running a graphical desktop, you should receive a popup notice
when this is initiated.

.. _repliversions:

.. code-block:: bash

  repliversions <file_path>

List the file versions that are available for a file in a versioned folder.
The version files listed are to be found in the ".archive" subfolder.
This is analogous to the Dolphin file manager context menu command
"Show Versions...".

Examples:
---------

.. code-block:: bash

  repliversion +/home/developer/test

Versions of files edited in the folder "/home/developer/test"
will be recorded in the folder "/home/developer/test/.archive";
any files edited in subfolders of "test" will be retained in
respective subfolders of the ".archive" subfolder.

.. code-block:: bash

  repliversion -/home/developer/test

Versions will no longer recorded in the folder
"/home/developer/test/.archive" (though the folder will remain...)
If you need to remove the ".archive" subfolder and any versions in it
you will have to do so as the Linux root account, using either
`"sudo" <https://wiki.debian.org/sudo>`_ or
`"su" <https://manpages.debian.org/bookworm/util-linux/su.1.en.html>`_,
along with the "rm" command.

.. code-block:: bash

  repliversions /home/developer/test/test1.txt

This will list all versions of "test1.txt" stored in the folder
"/home/developer/test/.archive"; a date, time, and file size for each
will be shown.