Update README and other docs

Author: thockin

README.md

@@ -6,21 +6,24 @@ use the [v3.x branch](https://github.com/kubernetes/git-sync/tree/release-3.x).
 
 # git-sync
 
-git-sync is a simple command that pulls a git repository into a local directory.
-It is a perfect "sidecar" container in Kubernetes - it can periodically pull
-files down from a repository so that an application can consume them.
+git-sync is a simple command that pulls a git repository into a local
+directory, waits for a while, then repeats.  As the remote repository chan ges,
+those changes will be synced locally.  It is a perfect "sidecar" container in
+Kubernetes - it can pull files down from a repository so that an application
+can consume them.
 
 git-sync can pull one time, or on a regular interval.  It can pull from the
 HEAD of a branch, from a git tag, or from a specific git hash.  It will only
-re-pull if the target of the run has changed in the upstream repository.  When
-it re-pulls, it updates the destination directory atomically.  In order to do
-this, it uses a git worktree in a subdirectory of the `--root` and flips a
-symlink.
+re-pull if the referenced target has changed in the upstream repository (e.g. a
+new commit on a branch).  It "publishes" each sync through a worktree and a
+named symlink.  This ensures an atomic update - consumers will not see a
+partially constructed view of the local repository.
 
 git-sync can pull over HTTP(S) (with authentication or not) or SSH.
 
-git-sync can also be configured to make a webhook call upon successful git repo
-synchronization. The call is made after the symlink is updated.
+git-sync can also be configured to make a webhook call or exec a command upon
+successful git repo synchronization. The call is made after the symlink is
+updated.
 
 ## Major update: v3.x -> v4.x
 
@@ -75,23 +78,36 @@ docker run -d \
     nginx
 ```
 
+### Flags
+
+git-sync has many flags and optional features (see the manual below).  Most of
+those flags can be configured through environment variables, but in most cases
+(with the obvious exception of passwords) flags are preferred, because the
+program can abort if an invalid flag is specified, but a misspelled environment
+variable will just be ignored.  We've tried to stay backwards-compatible across
+major versions (by accepting deprecated flags and environment variables), but
+some things have evolved, and users are encouraged to use the most recent flags
+for their major verion.
+
 ### Volumes
 
 The `--root` flag must indicate either a directory that either a) does not
 exist (it will be created); or b) exists and is empty; or c) can be emptied by
 removing all of the contents.
 
-Why?  Git demands to clone into an empty directory.  If the directory exists
-and is not empty, git-sync will try to empty it by removing everything in it
-(we can't just `rm -rf` the dir because it might be a mounted volume).  If that
-fails, git-sync will abort.
+Why?  Git really wants an empty directory, to avoid any confusion.  If the
+directory exists and is not empty, git-sync will try to empty it by removing
+everything in it (we can't just `rm -rf` the dir because it might be a mounted
+volume).  If that fails, git-sync will abort.
 
 With the above example or with a Kubernetes `emptyDir`, there is usually no
 problem.  The problematic case is when the volume is the root of a filesystem,
 which sometimes contains metadata (e.g. ext{2,3,4} have a `lost+found` dir).
-Git will not clone into such a directory (`fatal: destination path
-'/tmp/git-data' already exists and is not an empty directory`).  The only real
-solution is to use a sub-directory of the volume as the `--root`.
+The only real solution is to use a sub-directory of the volume as the `--root`.
+
+## More docs
+
+More documentation on specific topics can be [found here](./docs).
 
 ## Manual
 
@@ -102,7 +118,7 @@ NAME
     git-sync - sync a remote git repository
 
 SYNOPSIS
-    git-sync --repo=<repo> [OPTION]...
+    git-sync --repo=<repo> --root=<path> [OPTIONS]...
 
 DESCRIPTION
 
@@ -128,7 +144,8 @@ DESCRIPTION
 OPTIONS
 
     Many options can be specified as either a commandline flag or an environment
-    variable.
+    variable, but flags are preferred because a misspelled flag is a fatal
+    error while a misspelled environment variable is silently ignored.
 
     --add-user, $GITSYNC_ADD_USER
             Add a record to /etc/passwd for the current UID/GID.  This is
@@ -140,9 +157,6 @@ OPTIONS
             (200) and produce a series of key=value lines, including
             "username=<value>" and "password=<value>".
 
-    --change-permissions <int>, $GITSYNC_PERMISSIONS
-            Change permissions on the checked-out files to the specified mode.
-
     --cookie-file <string>, $GITSYNC_COOKIE_FILE
             Use a git cookiefile (/etc/git-secret/cookie_file) for
             authentication.
@@ -165,8 +179,8 @@ OPTIONS
     --exechook-command <string>, $GITSYNC_EXECHOOK_COMMAND
             An optional command to be executed after syncing a new hash of the
             remote repository.  This command does not take any arguments and
-            executes with the synced repo as its working directory.  The
-            environment variable $GITSYNC_HASH will be set to the git hash that
+            executes with the synced repo as its working directory.  The following
+            environment variables $GITSYNC_HASH will be set to the git hash that
             was synced.  The execution is subject to the overall --sync-timeout
             flag and will extend the effective period between sync attempts.
             This flag obsoletes --sync-hook-command, but if sync-hook-command
@@ -211,6 +225,13 @@ OPTIONS
             - off: Disable explicit git garbage collection, which may be a good
               fit when also using --one-time.
 
+    --group-write, $GITSYNC_GROUP_WRITE
+            Ensure that data written to disk (including the git repo metadata,
+            checked out files, worktrees, and symlink) are all group writable.
+            This corresponds to git's notion of a "shared repository".  This is
+            useful in cases where data produced by git-sync is used by a
+            different UID.  This replaces the older --change-permissions flag.
+
     -h, --help
             Print help text and exit.
 

cmd/git-sync/main.go

@@ -2245,7 +2245,7 @@ NAME
     git-sync - sync a remote git repository
 
 SYNOPSIS
-    git-sync --repo=<repo> [OPTION]...
+    git-sync --repo=<repo> --root=<path> [OPTIONS]...
 
 DESCRIPTION
 
@@ -2271,7 +2271,8 @@ DESCRIPTION
 OPTIONS
 
     Many options can be specified as either a commandline flag or an environment
-    variable.
+    variable, but flags are preferred because a misspelled flag is a fatal
+    error while a misspelled environment variable is silently ignored.
 
     --add-user, $GITSYNC_ADD_USER
             Add a record to /etc/passwd for the current UID/GID.  This is
@@ -2305,8 +2306,8 @@ OPTIONS
     --exechook-command <string>, $GITSYNC_EXECHOOK_COMMAND
             An optional command to be executed after syncing a new hash of the
             remote repository.  This command does not take any arguments and
-            executes with the synced repo as its working directory.  The following
-            environment variables $GITSYNC_HASH will be set to the git hash that
+            executes with the synced repo as its working directory.  The
+            $GITSYNC_HASH environment variable will be set to the git hash that
             was synced.  The execution is subject to the overall --sync-timeout
             flag and will extend the effective period between sync attempts.
             This flag obsoletes --sync-hook-command, but if sync-hook-command

docs/askpass-url.md

@@ -1,4 +1,4 @@
-# Using an Http Auth URL with git-sync
+# Using an HTTP auth URL with git-sync
 
 ## Step 1: Create a GIT_ASKPASS HTTP Service
 
@@ -8,15 +8,15 @@ Example of the service's output, see more at <https://git-scm.com/docs/gitcreden
 
 ```
 [email protected]
-password=ya29.mysecret
+password=mysecret
 ```
 
 ## Step 2: Configure git-sync container
 
 In your git-sync container configuration, specify the GIT_ASKPASS URL
 
-The credentials will pass in plain text, make sure the connection between git-sync
-and GIT ASKPASS Service are secure.
+The credentials will pass in plain text, so make sure the connection between
+git-sync and GIT ASKPASS Service is secure.
 
 See the askpass e2e test as an example.
 

docs/cookie-file.md

@@ -1,10 +1,10 @@
-# Using an Http Cookie File with git-sync
+# Using an HTTP cookie file with git-sync
 
-Git-sync supports use of an HTTP Cookie File for accessing git content.
+Git-sync supports use of an HTTP cookie file for accessing git content.
 
-## Step 1: Create Secret
+## Step 1: Create a Secret
 
-First, create a secret file from the git cookie file you wish to
+First, create a Kubernetes Secret from the git cookie file you wish to
 use.
 
 Example: if the cookie-file is `~/.gitcookies`:
@@ -16,9 +16,9 @@ kubectl create secret generic git-cookie-file --from-file=cookie_file=~/.gitcook
 Note that the key is `cookie_file`. This is the filename that git-sync will look
 for.
 
-## Step 2: Configure Pod/Deployment Volume
+## Step 2: Configure a Pod/Deployment volume
 
-In your Pod or Deployment configuration, specify a Volume for mounting the
+In your Pod or Deployment configuration, specify a volume for mounting the
 cookie-file Secret. Make sure to set `secretName` to the same name you used to
 create the secret (`git-cookie-file` in the example above).
 
@@ -30,13 +30,12 @@ volumes:
       defaultMode: 0440
 ```
 
-## Step 3: Configure git-sync container
+## Step 3: Configure a git-sync container
 
 In your git-sync container configuration, mount your volume at
 "/etc/git-secret". Make sure to pass the `--cookie-file` flag or set the
 environment variable `GITSYNC_COOKIE_FILE` to "true", and to use a git repo
-(`--repo` flag or `GITSYNC_REPO` env) is set to use a URL with the HTTP
-protocol.
+(`--repo` or `GITSYNC_REPO`) with an HTTP URL.
 
 ```yaml
 name: "git-sync"

docs/proxy.md

@@ -10,7 +10,7 @@ Lastly, [see similar issue for FluxCD](https://github.com/fluxcd/flux/pull/3152)
 
 ## Step 1: Create configuration
 
-Create a ConfigMap to store your configuration:
+Create a Kubernetes ConfigMap to store your configuration:
 
 ```bash
 cat << EOF >> /tmp/ssh-config
@@ -45,4 +45,4 @@ spec:
     - name: ssh-config
       configMap:
         name: ssh-config
-```
+```

v3-to-v4.md

@@ -127,6 +127,12 @@ specify `--depth=0`.
 The logging output for v3 was semi-free-form text.  Log output in v4 is
 structured and rendered as strict JSON.
 
+## Root dir
+
+git-sync v3 container images defaulted `--root` to "/tmp/git".  In v4, that has
+moved to "/git".  Users who mount a volume and expect to use the default
+`--root` must mount it on "/git".
+
 ## Other changes
 
 git-sync v3 would allow invalidly formatted env vars (e.g. a value that was