# Class parameters

A `VolumeAttributesClass` with `driverName: git.liken.sh` carries a
commit and push policy in `parameters`. Every parameter has a default,
so an empty class arms a volume with the defaults. The controller
refuses a class with an unknown or malformed parameter, naming the
first bad one.

| Parameter | Values | Default |
|---|---|---|
| `push.quiesce` | A Go duration, at least `5s`. The driver commits and pushes after the tree has been quiet this long. | `30s` |
| `push.maxLatency` | A Go duration, at least `push.quiesce`, or `never`. The driver pushes when the oldest unpushed commit is this old, whatever the tree is doing. | `5m`, or `push.quiesce` when that is longer |
| `commit.maxFileSize` | A Kubernetes quantity such as `1Mi`, or `0` for no limit. A larger file is not committed and is named in the events and the log. | `1Mi` |
| `commit.author` | `Name <email>`. The author and committer of every commit. | `git-csi-driver <git-csi-driver@liken.sh>` |
| `ignore` | Comma-separated `.gitignore` patterns, added to the repository's own. | empty |
| `metadata` | `true` or `false`. Whether modes, owners, and empty directories are recorded on `refs/git-csi/metadata` and replayed at restore. | `true` |

## Events

| Reason | When |
|---|---|
| `GitVolumeArmed` | The claim named a class of this driver. |
| `GitVolumeUnarmed` | The claim names no class of this driver. |
| `GitVolumePending` | The tree holds paths the driver has not committed. Posted when the set first becomes non-empty. |
| `GitVolumePushed` | A push succeeded, with the commit and the count of paths. |
| `GitVolumePushFailed` | A push failed, with git's error. |
| `GitVolumeFileSkipped` | A file over `commit.maxFileSize` was left out of a commit. |
| `GitVolumeRebased` | A rejected push rebased the tree onto upstream and landed, with the count of commits and the upstream commit. |
| `GitVolumeDiverged` | The volume moved to its side branch, after a push still rejected after three rebases, an aborted rebase, or a file the application and upstream both changed. |
| `GitVolumeHealed` | Upstream took the side branch's work, and the volume is back on its ref. |
| `GitVolumeNoPublishSecret` | The `PersistentVolume` names `nodeStageSecretRef` and no `nodePublishSecretRef`, so a restart of the driver loses the credential. Posted once for each stage and for each restart. |
| `GitVolumeUpstreamMoved` | The stage found that upstream moved while the tree held uncommitted writes, so it left the tree as it was. Posted on the claim when the driver finds it after the stage. |
| `GitVolumeRefDeleted` | The stage found that the remote no longer holds the ref, so the driver pushes nothing until the ref exists again. Posted on the claim when the driver finds it after the stage. |

Each fault, a failed push, a failed fetch, and an upstream that moved,
posts its event at the first failure after a success, and does not post
it again until a success ends that fault. A fault of one kind does not
hold back the event of a fault of another kind.

## The abnormal gauge

`git_csi_volume_abnormal`, labeled `namespace` and `volume`, is one for
an unarmed volume with pending paths, a failed push, a skipped file, an
unpushed commit older than `push.maxLatency`, an invalid class, a ref
that moved upstream while the tree held uncommitted writes, a diverged
volume, and a ref the remote no longer holds. The driver's log says
which.

## Metrics

Each gauge is labeled `namespace` and `claim`.

| Metric | Meaning |
|---|---|
| `git_csi_armed` | One when a class of this driver arms the volume. |
| `git_csi_pending_paths` | Paths the last scan found that the driver has not committed. |
| `git_csi_unpushed_commits` | Commits not yet on the remote. |
| `git_csi_last_push_timestamp_seconds` | When the last push succeeded. |
| `git_csi_push_failures_total` | Pushes that failed. |
| `git_csi_skipped_files` | Files over `commit.maxFileSize` in the tree. |
| `git_csi_diverged` | One while the volume pushes to its side branch. |
| `git_csi_volume_abnormal` | One while anything above is wrong. Labeled `namespace` and `volume`, not claim. |