git-sync

# NOTE: THIS DOCUMENT COVERS GIT-SYNC v4

This is the "master" branch, which is under development.  If you are looking 
for docs on older (v3) versions of git-sync, you probably want to 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, waits for a while, then repeats.  As the remote repository changes,
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 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 or exec a command upon
successful git repo synchronization. The call is made after the symlink is
updated.

## What it produces and why - the contract

git-sync has two required flags: `--repo`, which specifies which remote git
repo to sync, and `--root` which specifies a working directory for git-sync,
which presents an "API" of sorts.

The `--root` directory is _not_ the synced data.

Inside the `--root` directory git-sync stores the synced git state and other
things.  That directory may or may not respond to git commands - it's an
implementation detail.

One of the things in that directory is a symlink (see the `--link` flag) to the
most recently synced data.  This is how the data is expected to be consumed,
and is considered to be the "contract" between git-sync and consumers.  The
exact target of that symlink is an implementation detail, but the leaf
component of the target (i.e. `basename "$(readlink <link>)"`) is the git hash
of the synced revision.  This is also part of the contract.

git-sync looks for changes in the remote repo periodically (see the `--period`
flag) and will attempt to transfer as little data as possible and use as little
disk space as possible (see the `--depth` and `--git-gc` flags), but this is
not part of the contract.

### Why the symlink?

git checkouts are not "atomic" operations.  If you look at the repository while
a checkout is happening, you might see data that is neither exactly the old
revision nor the new.  git-sync "publishes" updates via the symlink to present
an atomic interface to consumers.  When the remote repo has changed, git-sync
will fetch the data _without_ checking it out, then create a new worktree, then
change the symlink to point to that new worktree.

git-sync does not currently have a no-symlink mode.

## Major update: v3.x -> v4.x

git-sync has under