kubernetes
/
git-sync
mirror of https://github.com/kubernetes/git-sync.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #500 from thockin/master 

Update README to latest (master)
This commit is contained in:
Kubernetes Prow Robot 2022-03-09 01:24:12 -08:00 committed by GitHub
parent e16e919af1 c7186a43b5
commit 9cb050efc6
1 changed files with 86 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
README.md
View File

@ -122,15 +122,32 @@ OPTIONS
Use a git cookiefile (/etc/git-secret/cookie_file) for Use a git cookiefile (/etc/git-secret/cookie_file) for
authentication. authentication.
--depth <int>, $GIT_SYNC_DEPTH
Create a shallow clone with history truncated to the specified
number of commits.
--error-file, $GIT_SYNC_ERROR_FILE --error-file, $GIT_SYNC_ERROR_FILE
The name of a file (under --root) into which errors will be The name of a file (under --root) into which errors will be
written. This must be a filename, not a path, and may not start written. This must be a filename, not a path, and may not start
with a period. (default: "", which means error reporting will be with a period. (default: "", which means error reporting will be
disabled) disabled)
--depth <int>, $GIT_SYNC_DEPTH --exechook-backoff <duration>, $GIT_SYNC_EXECHOOK_BACKOFF
Create a shallow clone with history truncated to the specified The time to wait before retrying a failed --exechook-command.
number of commits. (default: 3s)
--exechook-command <string>, $GIT_SYNC_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 SHA 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
is specified, it will take precedence.
--exechook-timeout <duration>, $GIT_SYNC_EXECHOOK_TIMEOUT
The timeout for the --exechook-command. (default: 30s)
--git <string>, $GIT_SYNC_GIT --git <string>, $GIT_SYNC_GIT
The git command to run (subject to PATH search, mostly for testing). The git command to run (subject to PATH search, mostly for testing).
@ -146,6 +163,18 @@ OPTIONS
Within quoted values, commas MAY be escaped, but are not required Within quoted values, commas MAY be escaped, but are not required
to be. Any other escape sequence is an error. (default: "") to be. Any other escape sequence is an error. (default: "")
--git-gc <string>, $GIT_SYNC_GIT_GC
The git garbage collection behavior: one of 'auto', 'always',
'aggressive', or 'off'. (default: auto)
- auto: Run "git gc --auto" once per successful sync. This mode
respects git's gc.* config params.
- always: Run "git gc" once per successful sync.
- aggressive: Run "git gc --aggressive" once per successful sync.
This mode can be slow and may require a longer --sync-timeout value.
- off: Disable explicit git garbage collection, which may be a good
fit when also using --one-time.
-h, --help -h, --help
Print help text and exit. Print help text and exit.
@ -162,11 +191,14 @@ OPTIONS
--http-bind). (default: false) --http-bind). (default: false)
--link <string>, $GIT_SYNC_LINK --link <string>, $GIT_SYNC_LINK
The name of the final symlink (under --root) which will point to the The path to at which to create a symlink which points to the
current git worktree. This must be a filename, not a path, and may current git directory, at the currently synced SHA. This may be an
not start with a period. The destination of this link (i.e. absolute path or a relative path, in which case it is relative to
readlink()) is the currently checked out SHA. (default: the leaf --root. The last path element is the name of the link and must not
dir of --repo) start with a period. Consumers of the synced files should always
use this link - it is updated atomically and should always be
valid. The basename of the target of the link is the current SHA.
(default: the leaf dir of --repo)
--man --man
Print this manual and exit. Print this manual and exit.
@ -182,12 +214,13 @@ OPTIONS
--password <string>, $GIT_SYNC_PASSWORD --password <string>, $GIT_SYNC_PASSWORD
The password or personal access token (see github docs) to use for The password or personal access token (see github docs) to use for
git authentication (see --username). NOTE: for security reasons, git authentication (see --username). NOTE: for security reasons,
users should prefer using a file for specifying the password (see users should prefer --password-file or $GIT_SYNC_PASSWORD for
--password-file). specifying the password.
--password-file <string>, $GIT_SYNC_PASSWORD_FILE --password-file <string>, $GIT_SYNC_PASSWORD
The path to password file which contains password or personal access The file from which the password or personal access token (see
token (see --password). github docs) to use for git authentication (see --username) will be
sourced.
--period <duration>, $GIT_SYNC_PERIOD --period <duration>, $GIT_SYNC_PERIOD
How long to wait between sync attempts. This must be at least How long to wait between sync attempts. This must be at least
@ -227,20 +260,14 @@ OPTIONS
The git submodule behavior: one of 'recursive', 'shallow', or 'off'. The git submodule behavior: one of 'recursive', 'shallow', or 'off'.
(default: recursive) (default: recursive)
--sync-hook-command <string>, $GIT_SYNC_HOOK_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
execution is subject to the overall --sync-timeout flag and will
extend the effective period between sync attempts.
--sync-timeout <duration>, $GIT_SYNC_SYNC_TIMEOUT --sync-timeout <duration>, $GIT_SYNC_SYNC_TIMEOUT
The total time allowed for one complete sync. This must be at least The total time allowed for one complete sync. This must be at least
10ms. This flag obsoletes --timeout, but if --timeout is specified, 10ms. This flag obsoletes --timeout, but if --timeout is specified,
it will take precedence. (default: 120s) it will take precedence. (default: 120s)
--username <string>, $GIT_SYNC_USERNAME --username <string>, $GIT_SYNC_USERNAME
The username to use for git authentication (see --password). The username to use for git authentication (see --password-file or
--password).
-v, --verbose <int> -v, --verbose <int>
Set the log verbosity level. Logs at this level and lower will be Set the log verbosity level. Logs at this level and lower will be
@ -250,7 +277,7 @@ OPTIONS
Print the version and exit. Print the version and exit.
--webhook-backoff <duration>, $GIT_SYNC_WEBHOOK_BACKOFF --webhook-backoff <duration>, $GIT_SYNC_WEBHOOK_BACKOFF
The time to wait before retrying a failed --webhook-url). The time to wait before retrying a failed --webhook-url.
(default: 3s) (default: 3s)
--webhook-method <string>, $GIT_SYNC_WEBHOOK_METHOD --webhook-method <string>, $GIT_SYNC_WEBHOOK_METHOD
@ -265,7 +292,8 @@ OPTIONS
The timeout for the --webhook-url. (default: 1s) The timeout for the --webhook-url. (default: 1s)
--webhook-url <string>, $GIT_SYNC_WEBHOOK_URL --webhook-url <string>, $GIT_SYNC_WEBHOOK_URL
A URL for optional webhook notifications when syncs complete. A URL for optional webhook notifications when syncs complete. The
header 'Gitsync-Hash' will be set to the git SHA that was synced.
EXAMPLE USAGE EXAMPLE USAGE
@ -284,10 +312,11 @@ AUTHENTICATION
and "git@example.com:repo" will try to use SSH. and "git@example.com:repo" will try to use SSH.
username/password username/password
The --username (GIT_SYNC_USERNAME) and --password The --username (GIT_SYNC_USERNAME) and --password-file
(GIT_SYNC_PASSWORD) flags will be used. To prevent password (GIT_SYNC_PASSWORD_FILE) or --password (GIT_SYNC_PASSWORD) flags
leaks, the GIT_SYNC_PASSWORD environment variable is almost always will be used. To prevent password leaks, the --password-file flag
preferred to the flag. or GIT_SYNC_PASSWORD environment variable is almost always
preferred to the --password flag.
A variant of this is --askpass-url (GIT_ASKPASS_URL), which A variant of this is --askpass-url (GIT_ASKPASS_URL), which
consults a URL (e.g. http://metadata) to get credentials on each consults a URL (e.g. http://metadata) to get credentials on each
@ -303,12 +332,19 @@ AUTHENTICATION
When --cookie-file (GIT_COOKIE_FILE) is specified, the associated When --cookie-file (GIT_COOKIE_FILE) is specified, the associated
cookies can contain authentication information. cookies can contain authentication information.
WEBHOOKS HOOKS
Webhooks are executed asynchronously from the main git-sync process. If a Webhooks and exechooks are executed asynchronously from the main git-sync
--webhook-url is configured, whenever a new hash is synced a call is sent process. If a --webhook-url or --exechook-command is configured, whenever
using the method defined in --webhook-method. Git-sync will retry this a new hash is synced the hook(s) will be invoked. For exechook, that means
webhook call until it succeeds (based on --webhook-success-status). If the command is exec()'ed, and for webhooks that means an HTTP request is
unsuccessful, git-sync will wait --webhook-backoff (default 3s) before sent using the method defined in --webhook-method. Git-sync will retry
re-attempting the webhook call. both forms of hooks until they succeed (exit code 0 for exechooks, or
--webhook-success-status for webhooks). If unsuccessful, git-sync will
wait --exechook-backoff or --webhook-backoff (as appropriate) before
re-trying the hook.
Hooks are not guaranteed to succeed on every single SHA change. For example,
if a hook fails and a new SHA is synced during the backoff period, the
retried hook will fire for the newest SHA.
``` ```