From 0db12ef8b87b37a9b7d55be5f8d4c2545b1dd0e4 Mon Sep 17 00:00:00 2001
From: Guilhem Moulin <guilhem@fripost.org>
Date: Fri, 27 Mar 2015 03:10:05 +0100
Subject: Add a 'git' command.

---
 cli/icevault.1 | 47 +++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 6 deletions(-)

(limited to 'cli/icevault.1')

diff --git a/cli/icevault.1 b/cli/icevault.1
index 0768b68..906cc8d 100644
--- a/cli/icevault.1
+++ b/cli/icevault.1
@@ -22,12 +22,14 @@ browser and the \fBicevault\fR client.
 
 Each form is stored in a separate file, encrypted separately with
 \fIgpg\fR(1); cleartext are never stored on disk.  Form history can be kept
-track of by adding the encrypted files to a VCS as binary blobs.  File
-paths are of the form ".../\fIscheme\fR/\fIhostname\fR/\fIidentity\fR"
-where \fIidentity\fR is an arbitrary user-chosen value (allowing
-multiple identities for a given site); since the URI of the active tab
-can be retrieved from the socket and since the URI of a stored form can
-be recovered from its file path, phishing attacks are easily detected.
+track of by versioning the encrypted files to a Git repository as binary
+blobs.  (Modification of the stored forms are then automatically
+committed to said repository.)  File paths are of the form
+".../\fIscheme\fR/\fIhostname\fR/\fIidentity\fR" where \fIidentity\fR is
+an arbitrary user-chosen value (allowing multiple identities for a given
+site); since the URI of the active tab can be retrieved from the socket
+and since the URI of a stored form can be recovered from its file path,
+phishing attacks are easily detected.
 
 Like Firefox's builtin password manager, IceVault has some heuristics to
 detect signup and password changing pages.  In these cases, and if the
@@ -76,6 +78,33 @@ if EDITOR is unset).  Upon exit, the file is reencrypted if the SHA-256
 digest of its content differs.  Note that formatting and comments may
 not be preserved by subsequent updates of the \fIidentity\fR file.
 
+.TP
+.B git\fR \fIGIT-COMMAND\fR [\fIGIT-ARG\fR...]
+Pass \fIGIT-COMMAND\fR [\fIGIT-ARG\fR...] as arguments to \fIgit\fR(1)
+using the configuration value for \fIstore\fR and that for \fIgit-dir\fR
+as the Git working tree and Git repository, respectively.
+\fIstore\fR is automatically created if it is not an existing directory.
+
+It is recommended to initialize the repository as follows:
+
+    \fBicevault git\fR init
+    echo '*.gpg diff=gpg' >"${XDG_DATA_HOME:-$HOME/.local/share}/icevault/.gitattributes"
+    \fBicevault git\fR add .gitattributes
+    \fBicevault git\fR commit \-m 'Add Git attributes for .gpg binary files.'
+    \fBicevault git\fR config diff.gpg.binary true
+    \fBicevault git\fR config diff.gpg.textconv 'gpg2 \-o \- \-\-decrypt'
+
+The textconv config option enable on-the-fly decryption prior to Git
+operations such as \fIdiff\fR or \fIgrep\fR, see \fIgitattributes\fR(5).
+For instance, grep'ing through the cleartext becomes trivial:
+
+    \fBicevault git\fR grep \-\-textconv \fIpattern\fR
+
+Signing each commit can be achieved as follows, see \fIgit-config\fR(1):
+
+    \fBicevault git\fR config commit.gpgsign true
+    \fBicevault git\fR config user.signingkey 0x39278DA8109E6244
+
 .TP
 .B insert\fR [\fB-f\fR, \fB--force\fR] [\fB-s\fR, \fB--socket=\fR\fIPATH\fR] [\fIidentity\fR]
 Create a new \fIscheme\fR://\fIhostname\fR/\fIidentity\fR URI available
@@ -121,6 +150,12 @@ XDG_CONFIG_HOME is unset.
 Empty lines and comments (starting with a "#" characters are ignored).
 Valid options are:
 
+.TP
+.I git-dir
+Path to the Git directory.  Can be an absolute path or a path relative
+to the working directory (specified with \fIstore\fR).
+(Default: ".git")
+
 .TP
 .I gpg
 The \fIgpg\fR(1) command to use.  Note that users of GnuPG 1.4.x will
-- 
cgit v1.2.3