.. _git:

===============
Git Directives
===============

Git directives allow you to specify a repository (*presently* gitlab or github...)
to which archived hard disk versions are to be replicated to.
Provided there is sufficient space in the repository,
each version of a file being edited will appear as a separate version
in the repo specified. Different folders being versioned can be replicated to
different git repos, be they public or private. One can even replicate one folder
to gitlab, and another to github.

..
.. image:: git.png

The following is a summary of settings that can be entered for a git repo:

* **git URL:** The full URL to the git; this will typically start with "https://", and end with ".git". Consult the git dashboard in your browser for the repo which you created to replicate to. The "Visit" button should take you to the browser dashboard for the repo.

* **Repo Type:** Usually this will be selected according to the host specified in the git URL ("gitlab.com" or "github.com"...); but if you are self-hosting your git, you can choose what standard of repo you are using.

* **Owner/Username:** The owner or username for the git repo.

* **Access Token:** A token that you specify for access to the repo. In gitlab parlance this is called a "Security Token"; in github parlance this is called an "Auth Token". It can be generated when you initially create the repo (often in a browser session...) Be sure it has sufficient privileges.

.. admonition:: Tip
   :class: tip

   It's a good idea to perform a "Test" of a token entered, to make sure it has privileges correctly configured. A test will upload to the repo a timestamp in a file called ".test"; it will then retrieve the file and confirm the timestamp is what was uploaded, to insure that the token is functioning properly.

* **Folder Path:** A "watched" folder path will replicate files to a top folder in the repo whose name matches the folder being versioned. If you choose a "root" folder path, then a full absolute path will be replicated to the repo. Example: if you are versioning the folder "/home/developer/test", and a watched folder is specified, then only a folder "test" will appear in the repo. But if you specify a "root" folder path, then the folder "/home", subfolder "/home/developer", and subfolder "/home/developer/test" will all appear in the repo. This can be useful for avoiding collisions in folder names; but using a "watched" folder can be easier to navigate to in your git browser dashboard if you know no folder name collisions will arise for your use case.