Branch Types
Git Town supports many different types and configurations of Git branches. When
properly configured, you can run git sync or git sync --all at any time and
each of your local branches will get synced in the specific ways it's supposed
to get synced or not synced.
Feature branches
Feature branches are the branches on which you typically make changes. They are typically cut from the main branch and get merged back into it. You can also cut feature branches from any other branch type if needed. Feature branches sync with their parent and tracking branch.
Main branch
The main branch is a perennial branch from which feature branches get cut by default.
Perennial branches
Perennial branches are long-lived branches. They have no parent and are never
shipped. Typical perennial branches are main, master, development,
production, staging, etc. Perennial branches often correspond with a cloud
environment with the same name.
Contribution branches
Contribution branches are for people who contribute commits to somebody else's
feature branch. You cannot propose or
ship contribution branches because those are
responsibilities of the person owning the branch you contribute to. For the same
reason git sync does not pull updates from the parent branch of a contribution
branch and always rebases your
local commits. Syncing removes contribution branches from your machine as soon
as their tracking branch is gone, even if you have unpushed local commits.
Killing a contribution branch only deletes your local copy
and not the tracking branch.
You can make any feature branch a contribution branch by running git contribute on it. Convert a contribution branch back to a feature branch by running git hack on it.
Observed branches
Observed branches are for people who want to observe the work of somebody else
without contributing commits to it. Similar to contribution branches, you cannot
propose or ship observed branches,
kill only deletes your local copy and not the tracking
branch, git sync always uses the
rebase sync-feature-strategy and
will remove a local observed branch as soon as its tracking branch is gone, even
if there are unmerged local commits.
Unlike with contributing branches, git sync does not push your local commits
made to an observed branch to its tracking branch.
You can make any feature branch an observed branch by running git observe on it. Convert an observed branch back to a feature branch by running git hack on it.
Parked Branches
Parked branches don't get synced at all unless you run git sync directly on a
parked branch. You might want to park a branch if you
- want to intentionally keep the branch at an older state
- don't want to deal with merge conflicts on this branch right now
- reduce load on your CI server by syncing only your actively developed local branches
You can park any feature branch by running git park on it.
Unpark a parked branch by running git hack on it.
Prototype Branches
A prototype branch is a local-only feature branch that incorporates updates from its parent branch but is not pushed to the remote repository. Prototype branches are useful when:
- the branch contains sensitive information, such as secrets, or potentially problematic code or data that could trigger alerts
- the developer prefers to keep their work private from the rest of the team during the initial stages of development
- you want to reduce CI pressure in the early phases of feature development when there isn't anything to test
Syncing prototype branches follows the sync-prototype-strategy or - if this setting isn't present - the sync-feature-strategy. This allows you to rebase your commits while working locally, and avoid rebasing when your commits become visible to others.
When you propose a prototype branch, it loses its
prototype status since it now has an official tracking branch that other people
look at. In this situation you can keep syncing without pushes by using the
--no-push sync option.
You can compress and ship prototype branches as usual. Parking and unparking a prototype branch maintains its prototype status. When you change a prototype branch to an observed or contribution branch it loses its prototype status.
To designate any feature branch as a prototype branch, execute git prototype on it. To convert a prototype branch to a feature branch, use git hack.