diff --git a/README.md b/README.md index 3bdd800..76ab501 100644 --- a/README.md +++ b/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= [OPTION]... + git-sync --repo= --root= [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=" and "password=". - --change-permissions , $GITSYNC_PERMISSIONS - Change permissions on the checked-out files to the specified mode. - --cookie-file , $GITSYNC_COOKIE_FILE Use a git cookiefile (/etc/git-secret/cookie_file) for authentication. @@ -165,8 +179,8 @@ OPTIONS --exechook-command , $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. diff --git a/cmd/git-sync/main.go b/cmd/git-sync/main.go index 89491aa..7ee697e 100644 --- a/cmd/git-sync/main.go +++ b/cmd/git-sync/main.go @@ -2245,7 +2245,7 @@ NAME git-sync - sync a remote git repository SYNOPSIS - git-sync --repo= [OPTION]... + git-sync --repo= --root= [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 , $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 diff --git a/docs/askpass-url.md b/docs/askpass-url.md index e8d25b3..ba3e088 100644 --- a/docs/askpass-url.md +++ b/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 > /tmp/ssh-config @@ -45,4 +45,4 @@ spec: - name: ssh-config configMap: name: ssh-config -``` \ No newline at end of file +``` diff --git a/v3-to-v4.md b/v3-to-v4.md index 92ff386..94924e6 100644 --- a/v3-to-v4.md +++ b/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