From 707d527e0355457d72ff09b060ff8098f84ee810 Mon Sep 17 00:00:00 2001 From: Tim Hockin Date: Thu, 23 Feb 2023 18:31:38 -0800 Subject: [PATCH] Add a doc about changing from v3 to v4 --- README.md | 5 +++ v3-to-v4.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 121 insertions(+) create mode 100644 v3-to-v4.md diff --git a/README.md b/README.md index 630637be1..55fc89b1b 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,11 @@ 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. +## Major update: v3.x -> v4.x + +git-sync has undergone many significant changes between v3.x and v4.x. [See +here](v3-to-v4.md) for more details. + ## Building it We use [docker buildx](https://github.com/docker/buildx) to build images. diff --git a/v3-to-v4.md b/v3-to-v4.md new file mode 100644 index 000000000..7daab3e27 --- /dev/null +++ b/v3-to-v4.md @@ -0,0 +1,116 @@ +# Converting from git-sync v3.x to v4.x + +Git-sync v4 is a significant change from v3. It includes several flag changes +(though many of the old flags are kept for backwards compatibility), but more +importantly it fundamentally changes the way the internal sync-loop works. + +## The v3 loop + +The way git-sync v3.x works is sort of like how a human might work: + + 1) `git clone ` + 2) `git fetch ` + 3) `git checkout ` + +This made the code somewhat complicated, since it had to keep track of whether +this was the first pass (clone) or a subsequent pass (fetch). This led to a +number of bugs related to back-to-back runs of git-sync, and some race +conditions. + +## The v4 loop + +In v4.x the loop is simpler - every pass is the same. This takes advantage of +some idempotent behaviors (e.g. `git init` is safe to re-run) and uses git more +efficiently. Instead of cloning a branch, git-sync will now fetch exactly the +commit (by SHA) it needs. This transfers less data and closes the race +condition where a symbolic name can change after `git ls-remote` but before +`git fetch`. + +## Flags + +The flag syntax parsing has changed in v4. git-sync v3 accept flags in Go's +own style: either `-flag` or `--flag` were accepted. git-sync v4 only accepts +long flag names in the more common two-dash style (`--flag`), and accepts short +(single-character) flags in the one-dash style (`-v 2`). + +The following does not detail every flag available in v4 - just the one that +existed in v3 and are different in v4. + +### Verbosity: `--v` -> `-v` or `--verbose` + +The change in flag parsing affects the old `--v` syntax. To set verbosity +either use `-v` or `--verbose`. For backwards compatibility, `--v` will be +used if it is specified. + +### Sync target: `--branch` and `--rev` -> `--ref` + +The old `--branch` and `--rev` flags are deprecated in favor of the new `--ref` +flag. `--ref` can be either a branch name, a tag name, or a commit hash (aka +SHA). For backwards compatibility, git-sync will still accept the old flags +and try to set `--ref` from them. + + |----------|---------|---------|------------------------------| + | --branch | --rev | --ref | meaning | + |----------|---------|---------|------------------------------| + | "" | "" | "HEAD" | remote repo's default branch | + | brname | "" | brname | remote branch `brname` | + | brname | "HEAD" | brname | remote branch `brname` | + | "" | tagname | tagname | remote tag `tagname` | + | other | other | "" | error | + |----------|---------|---------|------------------------------| + +### Log-related flags + +git-sync v3 exposed a number of log-related flags (e.g. `-logtostderr`). These +have all been removed. git-sync v4 always logs to stderr, and the only control +offered is the verbosity level (`-v / --verbose`). + +### Symlink: `--dest` -> `--link` + +The old `--dest` flag is deprecated in favor of `--link`, which more clearly +conveys what it does. The allowed values remain the same, and for backwards +compatibility, `--dest` will be used if it is specified. + +### Loop: `--wait` -> `--period` + +The old `--wait` flag took a floating-point number of seconds as an argument +(e.g. "0.1" = 100ms). The new `--period` flag takes a Go-style duration string +(e.g. "100ms" or "0.1s" = 100ms). For backwards compatibility, `--wait` will +be used if it is specified. + +### Failures: `--max-sync-failures` -> `--max-failures` + +The new name of this flag is shorter and captures the idea that any +non-recoverable error in the sync loop counts as a failure. For backwards +compatibility, `--max-sync-failures` will be used if it is specified. + +### Timeouts: `--timeout` -> `--sync-timeout` + +The old `--timeout` flag took an integer number of seconds as an argument. The +new `--sync-timeout` flag takes a Go-style duration string (e.g. "30s" or +"0.5m"). For backwards compatibility, `--timeout` will be used if it is +specified. + +### Manual: `--man` + +The new `--man` flag prints a man-page style help document and exits. + +## Defaults + +### Depth + +git-sync v3 would sync the entire history of the remote repo by default. v4 +syncs just one commit, by default. This can be a significant performance and +disk-space savings for large repos. Users who want the full history can +specify `--depth=0`. + +## Logs + +The logging output for v3 was semi-free-form text. Log output in v4 is +structured and rendered as strict JSON. + +## Other changes + +git-sync v3 would allow invalidly formatted env vars (e.g. a value that was +expected to be boolean holding an integer) and just ignore them with +a warning. v4 requires that they parse correctly.