diff --git a/README.md b/README.md index c912809..26f9695 100644 --- a/README.md +++ b/README.md @@ -120,9 +120,9 @@ OPTIONS variable. --add-user, $GIT_SYNC_ADD_USER - Add a record to /etc/passwd for the current UID/GID. This is needed - to use SSH (see --ssh) with an arbitrary UID. This assumes that - /etc/passwd is writable by the current UID. + Add a record to /etc/passwd for the current UID/GID. This is + needed to use SSH with an arbitrary UID (see --ssh). This assumes + that /etc/passwd is writable by the current UID. --askpass-url , $GIT_SYNC_ASKPASS_URL A URL to query for git credentials. The query must return success @@ -130,29 +130,29 @@ OPTIONS "username=" and "password=". --branch , $GIT_SYNC_BRANCH - The git branch to check out. (default: ) + The git branch to check out. If not specified, this defaults to + the default branch of --repo. --change-permissions , $GIT_SYNC_PERMISSIONS - Optionally change permissions on the checked-out files to the - specified mode. + Change permissions on the checked-out files to the specified mode. - --cookie-file, $GIT_SYNC_COOKIE_FILE + --cookie-file , $GIT_SYNC_COOKIE_FILE Use a git cookiefile (/etc/git-secret/cookie_file) for authentication. --depth , $GIT_SYNC_DEPTH Create a shallow clone with history truncated to the specified - number of commits. + number of commits. If not specified, this defaults to cloning the + full history of the repo. - --error-file, $GIT_SYNC_ERROR_FILE - 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 - with a period. (default: "", which means error reporting will be - disabled) + --error-file , $GIT_SYNC_ERROR_FILE + The name of an optional file (under --root) into which errors will + be written. This must be a filename, not a path, and may not start + with a period. --exechook-backoff , $GIT_SYNC_EXECHOOK_BACKOFF - The time to wait before retrying a failed --exechook-command. - (default: 3s) + The time to wait before retrying a failed --exechook-command. If + not specified, this defaults to 3 seconds ("3s"). --exechook-command , $GIT_SYNC_EXECHOOK_COMMAND An optional command to be executed after syncing a new hash of the @@ -165,11 +165,12 @@ OPTIONS is specified, it will take precedence. --exechook-timeout , $GIT_SYNC_EXECHOOK_TIMEOUT - The timeout for the --exechook-command. (default: 30s) + The timeout for the --exechook-command. If not specifid, this + defaults to 30 seconds ("30s"). --git , $GIT_SYNC_GIT - The git command to run (subject to PATH search, mostly for testing). - (default: git) + The git command to run (subject to PATH search, mostly for + testing). This defaults to "git". --git-config , $GIT_SYNC_GIT_CONFIG Additional git config options in 'key1:val1,key2:val2' format. The @@ -179,11 +180,12 @@ OPTIONS supported: '\n' => [newline], '\t' => [tab], '\"' => '"', '\,' => ',', '\\' => '\'. Within unquoted values, commas MUST be escaped. 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. --git-gc , $GIT_SYNC_GIT_GC - The git garbage collection behavior: one of 'auto', 'always', - 'aggressive', or 'off'. (default: auto) + The git garbage collection behavior: one of "auto", "always", + "aggressive", or "off". If not specified, this defaults to + "auto". - auto: Run "git gc --auto" once per successful sync. This mode respects git's gc.* config params. @@ -197,16 +199,16 @@ OPTIONS Print help text and exit. --http-bind , $GIT_SYNC_HTTP_BIND - The bind address (including port) for git-sync's HTTP endpoint. - (default: none) + The bind address (including port) for git-sync's HTTP endpoint. If + not specified, the HTTP endpoint is not enabled. --http-metrics, $GIT_SYNC_HTTP_METRICS - Enable metrics on git-sync's HTTP endpoint (see --http-bind). - (default: true) + Enable metrics on git-sync's HTTP endpoint, if it is enabled (see + --http-bind). --http-pprof, $GIT_SYNC_HTTP_PPROF - Enable the pprof debug endpoints on git-sync's HTTP endpoint (see - --http-bind). (default: false) + Enable the pprof debug endpoints on git-sync's HTTP endpoint, if it + is enabled (see --http-bind). --link , $GIT_SYNC_LINK The path to at which to create a symlink which points to the @@ -216,18 +218,19 @@ OPTIONS 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) + If not specified, this defaults to the leaf dir of --repo. --man Print this manual and exit. --max-failures , $GIT_SYNC_MAX_FAILURES The number of consecutive failures allowed before aborting (the - first sync must succeed), Setting this to -1 will retry forever - after the initial sync. (default: 0) + first sync must succeed), Setting this to a negative value will + retry forever after the initial sync. If not specified, this + defaults to 0, meaning any sync failure will terminate git-sync. --one-time, $GIT_SYNC_ONE_TIME - Exit after the first sync. + Exit after one sync. --password , $GIT_SYNC_PASSWORD The password or personal access token (see github docs) to use for @@ -238,18 +241,20 @@ OPTIONS --password-file , $GIT_SYNC_PASSWORD_FILE The file from which the password or personal access token (see github docs) to use for git authentication (see --username) will be - sourced. + read. --period , $GIT_SYNC_PERIOD How long to wait between sync attempts. This must be at least 10ms. This flag obsoletes --wait, but if --wait is specified, it - will take precedence. (default: 10s) + will take precedence. If not specified, this defaults to 10 + seconds ("10s"). --repo , $GIT_SYNC_REPO - The git repository to sync. + The git repository to sync. This flag is required. --rev , $GIT_SYNC_REV - The git revision (tag or hash) to check out. (default: HEAD) + The git revision (tag or hash) to check out. If not specified, + this defaults to "HEAD". --root , $GIT_SYNC_ROOT The root directory for git-sync operations, under which --link will @@ -258,33 +263,35 @@ OPTIONS which can be emptied by removing all of the contents. This flag is required. - --sparse-checkout-file, $GIT_SYNC_SPARSE_CHECKOUT_FILE + --sparse-checkout-file , $GIT_SYNC_SPARSE_CHECKOUT_FILE The path to a git sparse-checkout file (see git documentation for details) which controls which files and directories will be checked - out. + out. If not specified, the default is to check out the entire repo. --ssh, $GIT_SYNC_SSH Use SSH for git authentication and operations. --ssh-key-file , $GIT_SYNC_SSH_KEY_FILE - The SSH key to use when using --ssh. (default: /etc/git-secret/ssh) + The SSH key to use when using --ssh. If not specified, this + defaults to "/etc/git-secret/ssh". --ssh-known-hosts, $GIT_SYNC_KNOWN_HOSTS - Enable SSH known_hosts verification when using --ssh. - (default: true) + Enable SSH known_hosts verification when using --ssh. If not + specified, this defaults to true. --ssh-known-hosts-file , $GIT_SYNC_SSH_KNOWN_HOSTS_FILE The known_hosts file to use when --ssh-known-hosts is specified. - (default: /etc/git-secret/known_hosts) + If not specified, this defaults to "/etc/git-secret/known_hosts". --submodules , $GIT_SYNC_SUBMODULES - The git submodule behavior: one of 'recursive', 'shallow', or 'off'. - (default: recursive) + The git submodule behavior: one of "recursive", "shallow", or + "off". If not specified, this defaults to "recursive". --sync-timeout , $GIT_SYNC_SYNC_TIMEOUT The total time allowed for one complete sync. This must be at least 10ms. This flag obsoletes --timeout, but if --timeout is specified, - it will take precedence. (default: 120s) + it will take precedence. If not specified, this defaults to 120 + seconds ("120s"). --username , $GIT_SYNC_USERNAME The username to use for git authentication (see --password-file or @@ -292,25 +299,26 @@ OPTIONS -v, --verbose Set the log verbosity level. Logs at this level and lower will be - printed. (default: 0) + printed. --version Print the version and exit. --webhook-backoff , $GIT_SYNC_WEBHOOK_BACKOFF - The time to wait before retrying a failed --webhook-url. - (default: 3s) + The time to wait before retrying a failed --webhook-url. If not + specified, this defaults to 3 seconds ("3s"). --webhook-method , $GIT_SYNC_WEBHOOK_METHOD - The HTTP method for the --webhook-url (default: POST) + The HTTP method for the --webhook-url. If not specified, this defaults to "POST". --webhook-success-status , $GIT_SYNC_WEBHOOK_SUCCESS_STATUS The HTTP status code indicating a successful --webhook-url. Setting - this to -1 disables success checks to make webhooks fire-and-forget. - (default: 200) + this to -1 disables success checks to make webhooks + "fire-and-forget". If not specified, this defaults to 200. --webhook-timeout , $GIT_SYNC_WEBHOOK_TIMEOUT - The timeout for the --webhook-url. (default: 1s) + The timeout for the --webhook-url. If not specified, this defaults + to 1 second ("1s"). --webhook-url , $GIT_SYNC_WEBHOOK_URL A URL for optional webhook notifications when syncs complete. The @@ -369,4 +377,3 @@ HOOKS 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. -``` diff --git a/cmd/git-sync/main.go b/cmd/git-sync/main.go index 5e9229f..8735529 100644 --- a/cmd/git-sync/main.go +++ b/cmd/git-sync/main.go @@ -56,9 +56,9 @@ var flVerbose = pflag.IntP("verbose", "v", 0, "logs at this V level and lower will be printed") var flRepo = pflag.String("repo", envString("GIT_SYNC_REPO", ""), - "the git repository to clone") + "the git repository to clone (required)") var flBranch = pflag.String("branch", envString("GIT_SYNC_BRANCH", ""), - "the git branch to check out (defaults to repo's default branch)") + "the git branch to check out (defaults to the default branch of --repo)") var flRev = pflag.String("rev", envString("GIT_SYNC_REV", "HEAD"), "the git revision (tag or hash) to check out") var flDepth = pflag.Int("depth", envInt("GIT_SYNC_DEPTH", 0), @@ -67,11 +67,11 @@ var flSubmodules = pflag.String("submodules", envString("GIT_SYNC_SUBMODULES", " "git submodule behavior: one of 'recursive', 'shallow', or 'off'") var flRoot = pflag.String("root", envString("GIT_SYNC_ROOT", ""), - "the root directory for git-sync operations, under which --link will be created") + "the root directory for git-sync operations (required)") var flLink = pflag.String("link", envString("GIT_SYNC_LINK", ""), "the path (absolute or relative to --root) at which to create a symlink to the directory holding the checked-out files (defaults to the leaf dir of --repo)") var flErrorFile = pflag.String("error-file", envString("GIT_SYNC_ERROR_FILE", ""), - "the name of a file into which errors will be written under --root (defaults to \"\", disabling error reporting)") + "an optional file into which errors will be written under --root (defaults to disabled)") var flPeriod = pflag.Duration("period", envDuration("GIT_SYNC_PERIOD", 10*time.Second), "how long to wait between syncs, must be >= 10ms; --wait overrides this") var flSyncTimeout = pflag.Duration("sync-timeout", envDuration("GIT_SYNC_SYNC_TIMEOUT", 120*time.Second), @@ -1818,9 +1818,9 @@ OPTIONS variable. --add-user, $GIT_SYNC_ADD_USER - Add a record to /etc/passwd for the current UID/GID. This is needed - to use SSH (see --ssh) with an arbitrary UID. This assumes that - /etc/passwd is writable by the current UID. + Add a record to /etc/passwd for the current UID/GID. This is + needed to use SSH with an arbitrary UID (see --ssh). This assumes + that /etc/passwd is writable by the current UID. --askpass-url , $GIT_SYNC_ASKPASS_URL A URL to query for git credentials. The query must return success @@ -1828,29 +1828,29 @@ OPTIONS "username=" and "password=". --branch , $GIT_SYNC_BRANCH - The git branch to check out. (default: ) + The git branch to check out. If not specified, this defaults to + the default branch of --repo. --change-permissions , $GIT_SYNC_PERMISSIONS - Optionally change permissions on the checked-out files to the - specified mode. + Change permissions on the checked-out files to the specified mode. - --cookie-file, $GIT_SYNC_COOKIE_FILE + --cookie-file , $GIT_SYNC_COOKIE_FILE Use a git cookiefile (/etc/git-secret/cookie_file) for authentication. --depth , $GIT_SYNC_DEPTH Create a shallow clone with history truncated to the specified - number of commits. + number of commits. If not specified, this defaults to cloning the + full history of the repo. - --error-file, $GIT_SYNC_ERROR_FILE - 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 - with a period. (default: "", which means error reporting will be - disabled) + --error-file , $GIT_SYNC_ERROR_FILE + The name of an optional file (under --root) into which errors will + be written. This must be a filename, not a path, and may not start + with a period. --exechook-backoff , $GIT_SYNC_EXECHOOK_BACKOFF - The time to wait before retrying a failed --exechook-command. - (default: 3s) + The time to wait before retrying a failed --exechook-command. If + not specified, this defaults to 3 seconds ("3s"). --exechook-command , $GIT_SYNC_EXECHOOK_COMMAND An optional command to be executed after syncing a new hash of the @@ -1863,11 +1863,12 @@ OPTIONS is specified, it will take precedence. --exechook-timeout , $GIT_SYNC_EXECHOOK_TIMEOUT - The timeout for the --exechook-command. (default: 30s) + The timeout for the --exechook-command. If not specifid, this + defaults to 30 seconds ("30s"). --git , $GIT_SYNC_GIT - The git command to run (subject to PATH search, mostly for testing). - (default: git) + The git command to run (subject to PATH search, mostly for + testing). This defaults to "git". --git-config , $GIT_SYNC_GIT_CONFIG Additional git config options in 'key1:val1,key2:val2' format. The @@ -1877,11 +1878,12 @@ OPTIONS supported: '\n' => [newline], '\t' => [tab], '\"' => '"', '\,' => ',', '\\' => '\'. Within unquoted values, commas MUST be escaped. 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. --git-gc , $GIT_SYNC_GIT_GC - The git garbage collection behavior: one of 'auto', 'always', - 'aggressive', or 'off'. (default: auto) + The git garbage collection behavior: one of "auto", "always", + "aggressive", or "off". If not specified, this defaults to + "auto". - auto: Run "git gc --auto" once per successful sync. This mode respects git's gc.* config params. @@ -1895,16 +1897,16 @@ OPTIONS Print help text and exit. --http-bind , $GIT_SYNC_HTTP_BIND - The bind address (including port) for git-sync's HTTP endpoint. - (default: none) + The bind address (including port) for git-sync's HTTP endpoint. If + not specified, the HTTP endpoint is not enabled. --http-metrics, $GIT_SYNC_HTTP_METRICS - Enable metrics on git-sync's HTTP endpoint (see --http-bind). - (default: true) + Enable metrics on git-sync's HTTP endpoint, if it is enabled (see + --http-bind). --http-pprof, $GIT_SYNC_HTTP_PPROF - Enable the pprof debug endpoints on git-sync's HTTP endpoint (see - --http-bind). (default: false) + Enable the pprof debug endpoints on git-sync's HTTP endpoint, if it + is enabled (see --http-bind). --link , $GIT_SYNC_LINK The path to at which to create a symlink which points to the @@ -1914,7 +1916,7 @@ OPTIONS 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) + If not specified, this defaults to the leaf dir of --repo. --man Print this manual and exit. @@ -1922,10 +1924,11 @@ OPTIONS --max-failures , $GIT_SYNC_MAX_FAILURES The number of consecutive failures allowed before aborting (the first sync must succeed), Setting this to a negative value will - retry forever after the initial sync. (default: 0) + retry forever after the initial sync. If not specified, this + defaults to 0, meaning any sync failure will terminate git-sync. --one-time, $GIT_SYNC_ONE_TIME - Exit after the first sync. + Exit after one sync. --password , $GIT_SYNC_PASSWORD The password or personal access token (see github docs) to use for @@ -1936,18 +1939,20 @@ OPTIONS --password-file , $GIT_SYNC_PASSWORD_FILE The file from which the password or personal access token (see github docs) to use for git authentication (see --username) will be - sourced. + read. --period , $GIT_SYNC_PERIOD How long to wait between sync attempts. This must be at least 10ms. This flag obsoletes --wait, but if --wait is specified, it - will take precedence. (default: 10s) + will take precedence. If not specified, this defaults to 10 + seconds ("10s"). --repo , $GIT_SYNC_REPO - The git repository to sync. + The git repository to sync. This flag is required. --rev , $GIT_SYNC_REV - The git revision (tag or hash) to check out. (default: HEAD) + The git revision (tag or hash) to check out. If not specified, + this defaults to "HEAD". --root , $GIT_SYNC_ROOT The root directory for git-sync operations, under which --link will @@ -1956,33 +1961,35 @@ OPTIONS which can be emptied by removing all of the contents. This flag is required. - --sparse-checkout-file, $GIT_SYNC_SPARSE_CHECKOUT_FILE + --sparse-checkout-file , $GIT_SYNC_SPARSE_CHECKOUT_FILE The path to a git sparse-checkout file (see git documentation for details) which controls which files and directories will be checked - out. + out. If not specified, the default is to check out the entire repo. --ssh, $GIT_SYNC_SSH Use SSH for git authentication and operations. --ssh-key-file , $GIT_SYNC_SSH_KEY_FILE - The SSH key to use when using --ssh. (default: /etc/git-secret/ssh) + The SSH key to use when using --ssh. If not specified, this + defaults to "/etc/git-secret/ssh". --ssh-known-hosts, $GIT_SYNC_KNOWN_HOSTS - Enable SSH known_hosts verification when using --ssh. - (default: true) + Enable SSH known_hosts verification when using --ssh. If not + specified, this defaults to true. --ssh-known-hosts-file , $GIT_SYNC_SSH_KNOWN_HOSTS_FILE The known_hosts file to use when --ssh-known-hosts is specified. - (default: /etc/git-secret/known_hosts) + If not specified, this defaults to "/etc/git-secret/known_hosts". --submodules , $GIT_SYNC_SUBMODULES - The git submodule behavior: one of 'recursive', 'shallow', or 'off'. - (default: recursive) + The git submodule behavior: one of "recursive", "shallow", or + "off". If not specified, this defaults to "recursive". --sync-timeout , $GIT_SYNC_SYNC_TIMEOUT The total time allowed for one complete sync. This must be at least 10ms. This flag obsoletes --timeout, but if --timeout is specified, - it will take precedence. (default: 120s) + it will take precedence. If not specified, this defaults to 120 + seconds ("120s"). --username , $GIT_SYNC_USERNAME The username to use for git authentication (see --password-file or @@ -1990,25 +1997,26 @@ OPTIONS -v, --verbose Set the log verbosity level. Logs at this level and lower will be - printed. (default: 0) + printed. --version Print the version and exit. --webhook-backoff , $GIT_SYNC_WEBHOOK_BACKOFF - The time to wait before retrying a failed --webhook-url. - (default: 3s) + The time to wait before retrying a failed --webhook-url. If not + specified, this defaults to 3 seconds ("3s"). --webhook-method , $GIT_SYNC_WEBHOOK_METHOD - The HTTP method for the --webhook-url (default: POST) + The HTTP method for the --webhook-url. If not specified, this defaults to "POST". --webhook-success-status , $GIT_SYNC_WEBHOOK_SUCCESS_STATUS The HTTP status code indicating a successful --webhook-url. Setting - this to -1 disables success checks to make webhooks fire-and-forget. - (default: 200) + this to -1 disables success checks to make webhooks + "fire-and-forget". If not specified, this defaults to 200. --webhook-timeout , $GIT_SYNC_WEBHOOK_TIMEOUT - The timeout for the --webhook-url. (default: 1s) + The timeout for the --webhook-url. If not specified, this defaults + to 1 second ("1s"). --webhook-url , $GIT_SYNC_WEBHOOK_URL A URL for optional webhook notifications when syncs complete. The