aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorroot <root@localhost>2013-01-20 19:22:44 +0800
committerroot <root@localhost>2013-01-20 19:22:44 +0800
commitaeb3135bcb86b4aaeb4cc83f5e10fdc70949f256 (patch)
tree499cf8f3b2e916dbf6a9cf1cbe051cc3451da4ff
parent85e65ca48ed2c63ddd6a521bd0d08d3bf08e685c (diff)
downloadgit-remote-gcrypt-aeb3135bcb86b4aaeb4cc83f5e10fdc70949f256.zip
git-remote-gcrypt-aeb3135bcb86b4aaeb4cc83f5e10fdc70949f256.tar.gz
git-remote-gcrypt-aeb3135bcb86b4aaeb4cc83f5e10fdc70949f256.tar.bz2
Edit README
-rw-r--r--README.rst98
1 files changed, 47 insertions, 51 deletions
diff --git a/README.rst b/README.rst
index 1d87a44..60f2063 100644
--- a/README.rst
+++ b/README.rst
@@ -32,17 +32,15 @@ Quickstart
* Install ``git-remote-gcrypt`` by running the supplied ``install.sh`` script.
-* Create an encrypted remote by pushing to it:
+* Create an encrypted remote by pushing to it::
- ::
-
- git remote add cryptremote gcrypt::rsync://example.com:repo
- git push cryptremote master
- > gcrypt: Setting up new repository
- > gcrypt: Remote ID is :id:7VigUnLVYVtZx8oir34R
- > [ more lines .. ]
- > To gcrypt::[...]
- > * [new branch] master -> master
+ git remote add cryptremote gcrypt::rsync://example.com:repo
+ git push cryptremote master
+ > gcrypt: Setting up new repository
+ > gcrypt: Remote ID is :id:7VigUnLVYVtZx8oir34R
+ > [ more lines .. ]
+ > To gcrypt::[...]
+ > * [new branch] master -> master
Configuration
=============
@@ -50,47 +48,47 @@ Configuration
The following ``git-config(1)`` variables are supported:
``remote.<name>.gcrypt-participants``
- ..
+ ..
``gcrypt.participants``
- Space-separated list of GPG key identifiers. The remote is
- encrypted to these participants and only signatures from these
- are accepted. ``gpg -k`` lists all public keys you know.
+ Space-separated list of GPG key identifiers. The remote is encrypted
+ to these participants and only signatures from these are accepted.
+ ``gpg -k`` lists all public keys you know.
- When not set we encrypt to your default key and accept any valid
- signature. This behavior can also be requested explicitly by
- setting participants to ``simple``.
+ When not set we encrypt to your default key and accept any valid
+ signature. This behavior can also be requested explicitly by setting
+ participants to ``simple``.
- The ``gcrypt-participants`` setting on the remote takes precedence
- over the repository variable ``gcrypt.participants``.
+ The ``gcrypt-participants`` setting on the remote takes precedence
+ over the repository variable ``gcrypt.participants``.
``user.signingkey``
- (From regular git configuration) The key to use for signing.
- You should set ``user.signingkey`` if your default signing key is
- not part of the participant list.
+ (From regular git configuration) The key to use for signing. You
+ should set ``user.signingkey`` if your default signing key is not
+ part of the participant list.
Environment Variables
=====================
*GCRYPT_FULL_REPACK*
- This environment variable forces full repack when pushing.
+ This environment variable forces full repack when pushing.
Examples
========
-::
+How to set up a remote for two participants::
- git config gcrypt.participants YOURKEYID
- git remote add cryptremote gcrypt::rsync://example.com:repo
- git push cryptremote HEAD
+ git remote add cryptremote gcrypt::rsync://example.com:repo
+ git config remote.cryptremote.gcrypt-participants "KEY1 KEY2"
+ git push cryptremote master
How to use a git backend::
- # notice that the target repo must already exist and its
+ # notice that the target git repo must already exist and its
# `next` branch will be overwritten!
git remote add gitcrypt gcrypt::git@example.com:repo#next
- git push gitcrypt HEAD
+ git push gitcrypt master
-The URL fragment (`#next` here) indicates which branch is used.
+The URL fragment (`#next` here) indicates which backend branch is used.
Notes
=====
@@ -104,20 +102,20 @@ Collaboration
Dependencies
``rsync`` and ``curl`` for remotes ``rsync:`` and ``sftp:``
- respectively. The main executable is a script for any
- POSIX-compliant shell supporting ``local``.
+ respectively. The main executable requires a POSIX-compliant shell
+ that supports ``local``.
GNU Privacy Guard
- GPG 1.4 or 2 are both supported. You need a configured personal
- keypair. GPG configuration applies to algorithm choices for
- public-key encryption, symmetric encryption, and signing. See
- ``man gpg`` for more information.
+ Both GPG 1.4 and 2 are supported. You need a personal GPG key. GPG
+ configuration applies to algorithm choices for public-key
+ encryption, symmetric encryption, and signing. See ``man gpg`` for
+ more information.
Remote ID
- The generated Remote ID is not secret, it only exists to ensure that
- two repositories signed by the same user can be distinguished. You
- will see a warning if the Remote ID changes, which should
- only happen if the remote was re-created.
+ The Remote ID is not secret; it only ensures that two repositories
+ signed by the same user can be distinguished. You will see
+ a warning if the Remote ID changes, which should only happen if the
+ remote was re-created.
Repository Format
.................
@@ -139,15 +137,15 @@ Repository Format
|
| To write the repository:
|
-| Store each packfile ``P`` as ``P'`` = ``Encrypt(Ki, P)`` in filename ``Hi``
-| where ``Ki`` is a new random string and ``Hi = Hash(P')``
+| Store each packfile ``P`` as ``Encrypt(Ki, P) -> P'`` in filename ``Hi``
+| where ``Ki`` is a new random string and ``Hash(P') -> Hi``
| Store ``EncSign(B || L || R)`` in the manifest
|
| To read the repository:
|
| Decrypt and verify manifest using GPG keyring ``-> (B, L, R)``
| Warn if ``R`` does not match previously seen Remote ID
-| ``for each Hi, Ki in L``:
+| for each ``Hi, Ki in L``:
| Get file ``Hi`` from the server ``-> P'``
| Verify ``Hash(P')`` matches ``Hi``
| Decrypt ``P'`` using ``Ki`` -> ``P`` then open ``P`` with git
@@ -157,17 +155,17 @@ Repository Format
Manifest file
.............
-::
+Example manifest file (with ellipsis for brevity)::
$ gpg -d 91bd0c092128cf2e60e1a608c31e92caf1f9c1595f83f2890ef17c0e4881aa0a
542051c7cd152644e4995bda63cc3ddffd635958 refs/heads/next
3c9e76484c7596eff70b21cbe58408b2774bedad refs/heads/master
- pack :SHA256:f2ad50316fbca42c553810aec3709c24974585ec1b34aae77d5cd4ba67092dc4 z8YoAnFpMlWPIYG8wo1adewd4Fp7Fo3PkI2mND49P1qm
- pack :SHA256:a6e17bb4c042bdfa8e38856ee6d058d0c0f0c575ace857c4795426492f379584 82+k2cbiUn7i2cW0dgXfyX6wXGpvVaQGj5sF59Y8my5W
- keep :SHA256:f2ad50316fbca42c553810aec3709c24974585ec1b34aae77d5cd4ba67092dc4 1
+ pack :SHA256:f2ad50316...cd4ba67092dc4 z8YoAnFpMlW...3PkI2mND49P1qm
+ pack :SHA256:a6e17bb4c...426492f379584 82+k2cbiUn7...dgXfyX6wXGpvVa
+ keep :SHA256:f2ad50316...cd4ba67092dc4 1
repo :id:OYiSleGirtLubEVqJpFF
-Each item extends until newline, and matches one of the following forms:
+Each item extends until newline, and matches one of the following:
``<sha-1> <gitref>``
Git object id and its ref
@@ -195,7 +193,5 @@ License
git-remote-gcrypt is licensed under the terms of the GNU GPL version 2
(or at your option, any later version). See http://www.gnu.org/licenses/
-
-.. vim: ft=rst tw=72
.. this document generates a man page with rst2man
-
+.. vim: ft=rst tw=72 sts=4