From 05262ace2738347f71e94b7d6964000956afac81 Mon Sep 17 00:00:00 2001
From: Lars Wirzenius <liw@liw.fi>
Date: Tue, 29 Mar 2022 17:55:36 +0300
Subject: docs: add initial subplot for cachedir

Sponsored-by: author
---
 cachedir.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 cachedir.md

diff --git a/cachedir.md b/cachedir.md
new file mode 100644
index 0000000..b0646c0
--- /dev/null
+++ b/cachedir.md
@@ -0,0 +1,81 @@
+---
+title: "`cachedir`&mdash;cache directory tag management"
+author: The Obnam project
+template: rust
+bindings:
+  - lib/files.yaml
+  - lib/runcmd.yaml
+...
+
+# Introduction
+
+[Cache Directory Tagging Specification]: http://www.bford.info/cachedir/
+
+The `cachedir` utility manages tags for cache directories. A cache
+directory tag is specified in [Cache Directory Tagging
+Specification][], and is a file called `CACHEDIR.TAG`, where the first
+line consists of:
+
+~~~
+Signature: 8a477f597d28d172789f06886806bc55
+~~~
+
+Creating such files by hand is easy enough, but `cachedir` makes it a
+little easier.
+
+Many backup programs recognize cache directory tags and can exclude
+such directories.
+
+# Data files for testing
+
+We will use two files for testing: one is a valid `CACHEDIR.TAG` and
+the other isn't.
+
+~~~{#CACHEDIR.TAG .file}
+Signature: 8a477f597d28d172789f06886806bc55
+~~~
+~~~{#not-a-cache .file}
+This is not a cache directory tag.
+~~~
+
+
+# Managing cache directories
+
+_Requirement: The tool must find cache directories, and add and remove
+tags as requested._
+
+We should find no cache directories, if there aren't any.
+
+given an installed cachedir program
+
+~~~scenario
+when I run cachedir find .
+then stdout is exactly ""
+~~~
+
+When we create a directory, and a `CACHEDIR.TAG` file with the wrong
+contents, it's not a cache directory.
+
+~~~scenario
+given a directory foo
+given file foo/CACHEDIR.TAG from not-a-tag
+when I run cachedir .
+then stdout is exactly ""
+~~~
+
+When we create an actual tag, the directory is found.
+
+~~~scenario
+given a directory bar
+when I run cachedir tag bar
+when I run cachedir find .
+then stdout contains "/bar"
+~~~
+
+Finally, we should again find no cache directories if we remove that tag.
+
+~~~scenario
+when I run cachedir untag bar
+when I run cachedir find .
+then stdout is exactly ""
+~~~
-- 
cgit v1.2.1