From 3298f560944f5764bece8267e1e7f07100ec4fd1 Mon Sep 17 00:00:00 2001
From: Gustav Eek <gustav.eek@fripost.org>
Date: Fri, 23 Oct 2020 00:25:32 +0200
Subject: [PATCH] [repo-encrypt] Document

The added file *repo-encrypt.mdwn* documents the software. References
are provided in *README*.
---
 README                | 18 +++++++++++
 doc/repo-encrypt.mdwn | 71 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+)
 create mode 100644 doc/repo-encrypt.mdwn

diff --git a/README b/README
index a7b3912..9bd6a2b 100644
--- a/README
+++ b/README
@@ -56,3 +56,21 @@ Help
 Some scripts include help command, in that case type
 
 	$ <script> --help
+
+
+Further documentation
+---------------------
+
+Some scripts are more complex. Visit their separate documentation:
+
+ * [Notes on Repo Encrypt](doc/repo-encrypt.mdwn)
+
+
+Development
+===========
+
+Please put scripts in this repository. Write help routines to fulfil
+above promise. Ad bash completion in *bash_completion.d*.
+
+
+
diff --git a/doc/repo-encrypt.mdwn b/doc/repo-encrypt.mdwn
new file mode 100644
index 0000000..0258727
--- /dev/null
+++ b/doc/repo-encrypt.mdwn
@@ -0,0 +1,71 @@
+% Notes on Repo Encrypt
+
+# Plans of improvements
+
+## TODO Switch to bare repo
+
+Instead of copying one should initiate a bare repository and push to
+that. This holds for commands *encrypt*, which operates on the whole
+repository. Copying was (is):
+
+    cp -R .git "$tmp_dir/$parent.git"
+
+A corresponding bare version should be:
+
+    git init --bare "$tmp_dir/$parent.git"
+    git push --all "$tmp_dir/$parent.git"
+
+## TODO Implement fetching and pushing
+
+Implement commands *fetch* and *push*. Synopsis:
+
+```
+repo-encrypt fetch <origin-filename>
+
+repo-encrypt push <origin-filename> <destination-directory>
+
+decrypt
+
+repo-encrypt push <destination> <refspec>
+
+```
+
+## Push
+
+The *push* command requires (`set -e`) destination repository exists,
+corresponding to `<repository>` in `git push` synopsis. The workflow:
+
+ 1. Refresh temporary repository:
+     1. Decrypt to temporary
+     2. Extract archive
+ 2. Execute native Git push command
+ 3. Replace remote
+     1. Archive
+     2. Encrypt to remote
+     3. Drop temporary files
+
+In all other respect, results should be similar to encrypt
+
+## Fetch
+
+Fetch command will fetch all or some branches:
+
+ 1. Refresh temporary repository:
+     1. Decrypt to temporary
+     2. Extract archive
+ 2. Execute native Git fetch command
+ 3. Drop temporary
+
+The fetch will produce `FETCH.HEAD` or similar:
+
+    git fetch /tmp/parent.git
+
+This according to Git help, `git help fetch`: `<repository>` and
+`REMOTES` in `git help fetch`.
+
+# TODO Implement caching
+
+As of now, every command starts from scratch and creates temporary
+repository, e.g. */tmp/<parent>.git*. Instead use:
+*~/.cache/repo-encrypt/<hash>.git*. The hash is based on remote
+repository path. Consult file before updates.
-- 
2.39.2