Add docs for Git

docs/SUMMARY.md

@@ -14,6 +14,8 @@
     - [Systemd](./recipes/os/systemd.md)
     - [Users](./recipes/os/users.md)
   - [Filesystem Recipes](./recipes/filesystem/index.md)
+    - [Fridge Recipes](./recipes/filesystem/fridge.md)
+    - [Git Recipes](./recipes/filesystem/git.md)
   - [Database Recipes](./recipes/database/index.md)
     - [Postgres](./recipes/database/postgres.md)
   - [Docker](./recipes/docker.md)

docs/recipes/filesystem/git.md

@@ -0,0 +1,40 @@
+# Git
+
+Git is a version control system.
+
+| Recipe | Needs | Provides |
+| -----: | ----- | -------- |
+| [`git`](#git) | `directory` | `directory` `file`? `directory`? |
+
+
+## `git`
+
+Checks out a Git repository to a location on disk.
+You must specify exactly one of `ref` or `branch`.
+
+**Preconditions:** The remote repository must exist and be accessible. The specified commit, tag or branch must exist.
+
+**Postconditions:** The repository will be checked out on disk at the specified commit.
+
+**Provides:** `directory({dest})`, `file({dest}/{each file entry in expect})`, `directory({dest}/{each dir entry in expect})`
+
+| Argument | Accepted Values | Default | Description |
+| -------: | --------------- | ------- | ----------- |
+| src | string | *required* | This is the URL to the git 'remote'. Common formats are `https://gitplace.example.org/user/repo.git` or `git@example.org:repo.git`. |
+| dest | path | *required* | This is the path to the directory to check out the repository at. |
+| ref | string | *semi-optional* | Commit hash or tag name to check out. |
+| branch | string | *semi-optional* | Branch name to check out. The branch must exist on the remote. |
+| expect | list of paths relative to repository root | *optional* | The specified files and directories will be checked for existence after the repository is checked out. Directories are indicated by a trailing `/`. The specified files/directories are provided as resources. |
+| submodules | true or false | false | Whether to update submodules or not. |
+| deploy_key | fridge path | *optional* | If specified, the specified SSH private key will be used to clone the Git repository. Useful in conjunction with various Git providers' (e.g. Gitea) 'Deploy keys' feature, granting read-only access to a single repository. |
+
+### Example
+
+```scoml
+[[git]]  Clone the abc git repository
+src = "gitea@bics.ga:reivilibre/abc.git"
+dest = "/home/abc/abc"
+ref = "61242b97d6"
+expect = ["setup.py", "abc/"]
+deploy_key = "Common/gitea_deploy_key.frozen"
+```