git town sync
git town sync [--all] [--detached] [--dry-run] [--no-push] [--stack] [--verbose]
The sync command ("synchronize this branch") updates your local Git workspace with what happened in the rest of the repository.
Merge conflicts are not fun and can break code. Minimize them by syncing your
branches frequently. Git town knows how to sync many different types of
branches. When properly configured, git town sync --all can synchronize all
your local branches the right way without losing changes, even in edge cases.
You can (and should) sync all branches many times per day without thinking about it, even in the middle of ongoing work. If a sync goes wrong, you can safely go back to the exact state you repo was in before the sync by running git town undo.
- pulls and pushes updates from all parent branches and the tracking branch
- deletes branches whose tracking branch was deleted at the remote if they contain no unshipped changes
- removes commits of deleted branches from their descendent branches, unless when using the merge sync strategy.
- safely stashes away uncommitted changes and restores them when done
- does not pull, push, or merge depending on the configured branch type
If the parent branch is not known, Git Town looks for a pull/merge request for this branch and uses its parent branch. Otherwise it prompts you for the parent.
--all / -a
By default this command syncs only the current branch. The --all aka -a
parameter makes Git Town sync all local branches.
--detached / -d
The --detached aka -d flag does not pull updates from the main or perennial
branch at the root of your branch hierarchy. This allows you to keep your
branches in sync with each other and decide when to pull in changes from other
developers.
--dry-run
Use the --dry-run flag to test-drive this command. It prints the Git commands
that would be run but doesn't execute them.
--no-push
The --no-push argument disables all pushes of local commits to their tracking
branch.
--stack / -s
The --stack aka -s parameter makes Git Town sync all branches in the stack
that the current branch belongs to.
--verbose / -v
The --verbose aka -v flag prints all Git commands run under the hood to
determine the repository state.
Configuration
sync-perennial-strategy configures whether perennial branches merge their tracking branch or rebase against it.
sync-feature-strategy configures whether feature branches merge their parent and tracking branches or rebase against them.
If the repository contains a Git remote called upstream and the
sync-upstream setting is enabled, Git Town
also pulls new commits from the upstream's main branch.
sync-tags configures whether Git Town syncs Git
tags with the origin remote.
Why does git-sync sometimes update a local branch whose tracking branch was deleted before deleting it?
If a remote branch was deleted at the remote, it is considered obsolete and "git town sync" will remove its local counterpart. To guarantee that this doesn't lose unshipped changes in the local branch, "git town sync" needs to prove that the branch to be deleted contains no unshipped changes.
The easiest way to prove that is when the local branch was in sync with its
tracking branch before Git Town runs git fetch. This is another reason to run
git town sync regularly.
If a local shipped branch is not in sync with its tracking branch on your machine, Git Town must check for unshipped local changes by diffing the branch to delete against its parent branch. Only branches with an empty diff can be deleted safely. For this to work, Git Town needs to sync the branch first, even if it's going to be deleted right afterwards.