High-level CLI for Git

Git Town solves the problem that using the Git CLI correctly is cumbersome and repetitive, and therefore many developers don’t use Git to its full potential.

Git isn’t just a version control system; it’s a flexible framework for creating various version control workflows. This flexibility means that most of us end up using ad-hoc workflows, either in our heads or through custom Bash scripts tailored to our needs. These manual workflows often lack proper specifications and don’t handle errors and edge cases well.

Git Town is a reusable implementation of Git workflows for common usage scenarios like contributing to a centralized code repository on platforms like GitHub, GitLab, Bitbucket, Gitea, or Codeberg. Think of Git Town as your Bash scripts for Git, but fully engineered with rock-solid support for many use cases, edge cases, and error conditions.

With Git Town you can keep using Git the way you do now, but with extra commands to create various branch types, keep them in sync, compress, review, and ship them efficiently.

Git Town is compatible with most common branching models like GitHub Flow, Git Flow, GitLab Flow, trunk-based development and even committing straight into the main branch. Git Town has special support for mono-repos and stacked changes. See also this external review.

What our users say

#Gittown you sexy beast! @GitTown
— Elegant Development (@elegant_dev)

Amazing @GitTown rocks! 🚀 https://t.co/S5ouIBx2fe
— Jose Quintana (@joseluis_q)

All doable w/ just git, but git-town is a simpler mental-model and way less keystrokes
— Ryan Nystrom (@_ryannystrom)

I've been using git-town along git-flow for a little while and it's been really nice https://t.co/E5nwHuXP1C
— dan reeves 🏳️‍🌈 (@dnrvs)

Wow @GitTown looks great, type less git commands for common branch/pr workflows. Similar to @github’s “hub” but looks more powerful, and it logs the fit commands it runs under the hood. pic.twitter.com/PxGs76TS5I
— Gregor (@gr2m)

Supercharge your workflow with Git by relying on this surprisingly powerful and quite useful plugin that provides you with a series of extra Git commands.

Softpedia article about Git Town

Q & A

Does Git Town enforce any specific conventions for branches or commits?

No, Git Town doesn’t impose any rules for branch or commit naming. It works with a wide range of Git branching strategies and workflows. If you find it doesn’t mesh with your specific setup, reach out to us.

Which Git branching models does Git Town support?

Git Town is flexible enough to support the most popular branching models like GitHub Flow, Git Flow, GitLab Flow, trunk-based development. It even works if you commit directly to the main branch!

How is Git Town different from the git-flow tool?

git-flow is a specialized Git extension designed around providing opinionated support for the Git Flow branching model. It doesn’t help with keeping your branches or team in sync. Git Town, on the other hand, doesn’t mind which branching model you use—it focuses on syncing your team’s work and keeping your repo tidy by cleaning up old branches. You can use Git Town alongside git-flow if that fits your workflow.

Is Git Town compatible with other Git tools?

Yes, we try to be good citizens in the Git ecosystem. If you run into compatibility issues, please let us know!

Does my whole team have to use Git Town?

No, you can get value from Git Town even if you’re the only one using it. It simply automates the Git commands that you would (should) normally run.

Installation

Git Town ships as a single self-contained binary. It calls the Git executable that is already installed on your machine.

macOS

You can install Git Town on macOS via Homebrew:


brew install git-town

Installation via MacPorts is also supported:


sudo port install git-town

Windows

You can install Git Town on Windows using:

Chocolatey: choco install git-town
Scoop: scoop install git-town
the Git Town Windows installer

If you use the Windows Subsystem for Linux, please install wsl-open to allow the commands git town repo and git town propose to open a browser window for you.

Linux

On Debian-based systems, download the .deb file matching your CPU architecture and run:


sudo apt-get install git-town_linux_intel_64.deb

On RedHat-based systems download the .rpm file matching your CPU architecture and run


rpm -i git-town_linux_intel_64.rpm

On Arch Linux, install the git-town package from the AUR. Or download the matching .pkg.tar.zst file for your architecture and run:


sudo pacman -U <filename>

You can also install Git Town on Linux via Homebrew for Linux:


brew install git-town

You can also install Git Town manually or compile from source.

BSD

You can install Git Town on BSD via freshports or by downloading the matching binaries from the GitHub release.

Manual installation


curl https://www.git-town.com/install.sh | sh

For a fully custom installation, download the archive matching your CPU architecture, extract it, and move the git-town executable into a directory listed in your $PATH, for example /usr/local/bin.

Compile from source

If you have the Go compiler installed, you can compile the latest version of Git Town from source by running:


go get github.com/git-town/git-town/v20

New releases

Subscribe to the Git Town release feed to get notifications about new releases.

Uninstall

To remove Git Town from your system:

Remove the Git Town configuration from your repositories: in each repo, run git town config remove
If your operating system or package manager provides an uninstaller for Git Town, run it. If you installed Git Town manually, delete the binary.

Set up configuration

If your repository already contains a .git-branches.toml or .git-town.toml file, you are good to go. If not or something doesn’t work, run Git Town’s setup assistant. It walks you through every configuration option and gives you a chance to adjust it.


git town config setup

You can find more background around how Git Town stores configuration in the overview of all configuration options.

Access tokens

API access multiplies Git Town’s utility:

if the parent of a branch is not known, Git Town can look for a pull requests of this branch and uses their parent branch
updates affected pull requests when you prepend, rename, remove branches or change their parent
click the “merge” button on a pull request from your CLI

Configuring API access takes only one minute. Here is how you do it:

GitHub: access token
GitLab: access token
Bitbucket: username and app password
Gitea: access token
Codeberg: access token

How To …

This section covers practical tips and workflows for getting the most out of Git Town. Learn how to:

Set up shell autocompletion
Show the currently interrupted Git Town command in your shell prompt
Add a breadcrumb of your current stack to GitHub pull requests
Use Git Town with forked repositories
Create and propose hotfixes
Work with stacked changes
Integrate Git Town with LazyGit

Working with Forked Repositories

Git Town fully supports fork-based workflows. After cloning your fork locally, add an upstream remote pointing to the original repo you forked from. You can do this using the Git remote command:


git remote add upstream <Git URL>

Once set up, git town sync will automatically pull in updates from the upstream repository. When you’re ready to submit your changes, git town propose creates pull requests from your fork to the original project.

The Git Town GitHub action adds a visual breadcrumb to new pull requests, showing where the branch sits in your stack. This makes it easy for reviewers to understand the context of a PR at a glance.

example stack created by the Git Town GitHub action

Integrate Git Town with Lazygit

Example lazygit configuration file to integrate Git Town:


customCommands:
  - key: "Y"
    context: "global"
    description: "Git-Town sYnc"
    command: "git-town sync --all"
    stream: true
    loadingText: "Syncing"
  - key: "U"
    context: "global"
    description: "Git-Town Undo (undo the last git-town command)"
    command: "git-town undo"
    prompts:
      - type: "confirm"
        title: "Undo Last Command"
        body: "Are you sure you want to Undo the last git-town command?"
    stream: true
    loadingText: "Undoing Git-Town Command"
  - key: "!"
    context: "global"
    description: "Git-Town Repo (opens the repo link)"
    command: "git-town repo"
    stream: true
    loadingText: "Opening Repo Link"
  - key: "a"
    context: "localBranches"
    description: "Git-Town Append"
    prompts:
      - type: "input"
        title: "Enter name of new child branch. Branches off of '{{.CheckedOutBranch.Name}}'"
        key: "BranchName"
    command: "git-town append {{.Form.BranchName}}"
    stream: true
    loadingText: "Appending"
  - key: "h"
    context: "localBranches"
    description: "Git-Town Hack (creates a new branch)"
    prompts:
      - type: "input"
        title: "Enter name of new branch. Branches off of 'Main'"
        key: "BranchName"
    command: "git-town hack {{.Form.BranchName}}"
    stream: true
    loadingText: "Hacking"
  - key: "K"
    context: "localBranches"
    description: "Git-Town Delete (deletes the current feature branch and sYnc)"
    command: "git-town delete"
    prompts:
      - type: "confirm"
        title: "Delete current feature branch"
        body: "Are you sure you want to delete the current feature branch?"
    stream: true
    loadingText: "Deleting Feature Branch"
  - key: "p"
    context: "localBranches"
    description: "Git-Town Propose (creates a pull request)"
    command: "git-town propose"
    stream: true
    loadingText: "Creating pull request"
  - key: "P"
    context: "localBranches"
    description: "Git-Town Prepend (creates a branch between the curent branch and its parent)"
    prompts:
      - type: "input"
        title: "Enter name of the for child branch between '{{.CheckedOutBranch.Name}}' and its parent"
        key: "BranchName"
    command: "git-town prepend {{.Form.BranchName}}"
    stream: true
    loadingText: "Prepending"
  - key: "S"
    context: "localBranches"
    description: "Git-Town Skip (skip branch with merge conflicts when syncing)"
    command: "git-town skip"
    stream: true
    loadingText: "Skiping"
  - key: "G"
    context: "files"
    description: "Git-Town GO aka:continue (continue after resolving merge conflicts)"
    command: "git-town continue"
    stream: true
    loadingText: "Continuing"

Display the currently pending Git Town command in your shell prompt

You can configure your shell prompt to display a reminder for when a Git Town command was interrupted in the middle and is waiting to be continued. This helps you remember to run git town continue before moving on.

Bash

To add this status indicator to your Bash prompt, add the following to your .bashrc:


function git_town_status {
    local pending_gittown_command=$(git town status --pending)
    if [ -n "$pending_gittown_command" ]; then
      echo -e " \033[30;43m $pending_gittown_command \033[0m "
    fi
}

PS1='$(git_town_status)> '

Zsh

For Zsh, add the following to your ~/.zshrc:


git_town_status() {
  local git_status
  git_status=$(git town status --pending)
  if [[ -n "$git_status" ]]; then
    echo "%K{yellow}%F{black} $git_status %f%k "
  fi
}

setopt PROMPT_SUBST
PROMPT='$(git_town_status)> '

Fish

For Fish shell, update your ~/.config/fish/config.fish and override the fish_prompt function:


function fish_prompt
  set -f pending_gittown_command (git-town status --pending)
  if [ -n "$pending_gittown_command" ]
    set -f yellow_pending_gittown_command (set_color -b yellow)(set_color black)(echo " $pending_gittown_command ")(set_color normal)' '
  else
    set -f yellow_pending_gittown_command ''
  end
  printf '%s> ' $yellow_pending_gittown_command
end

Creating and shipping hotfixes

Hotfixes differ from regular changes in that they’re based on a different perennial branch—typically something like production or staging—and get merged back into that branch.

For example, to create a hotfix from the production branch:


git checkout production
git append my-hotfix

Now, when you run git town sync, it’ll sync your my-hotfix branch with production instead of the main branch. When you’re ready to submit the fix, git town propose will create a pull request from your hotfix branch back into production.

Commands

Run git town for an overview of all Git Town commands and git town help <command> for help with individual commands.

Basic workflow

git town hack - create a new feature branch
git town sync - update the current branch with all ongoing changes
git town switch - switch between branches visually
git town propose - propose to ship a branch

Dealing with errors

git town continue - continue after you resolved the merge conflict
git town skip - when syncing all branches, ignore the current branch and continue with the next one
git town status - display available commands
git town undo - undo the last completed Git Town command

Stacked changes

git town append - create a new feature branch as a child
git town detach - move a branch out of a stack
git town diff-parent - show the changes committed to a branch
git town merge - merges the current branch with its parent
git town prepend - create a new feature branch between the current branch and its parent
git town set-parent - change the parent of a feature branch
git town swap - swap the position of this branch with its parent

Limit branch syncing

git town contribute - stop syncing some feature branches with their parents
git town observe - stop syncing your contributions to some feature branches
git town park - suspend syncing some of your feature branches altogether
git town prototype - sync but don’t push a local feature branch

Git Town setup

git town completion - generate completion scripts for Bash, zsh, fish & PowerShell.
git town config - display or update your Git Town configuration
git town config setup - setup assistant
git town offline - enable/disable offline mode

Additional commands

git town branch - display the local branch hierarchy and types
git town compress - squash all commits on a branch branches down to a single commit
git town delete - delete a feature branch
git town help - help about any command
git town rename - rename a branch
git town repo - view the Git repository in the browser
git town ship - deliver a completed feature branch

Typical development workflow

The following four Git Town commands automate the typical development workflow:

You start hacking by running git town hack to create a feature branch.
While coding you run git town sync to keep your feature branch up to date with commits that you or other developers make into the main branch. This prevents your feature branch from deviating too much from the main code line.
If your team does pull requests, you can run git town propose to create a new pull request.
git town ship delivers the feature branch.

git town hack


git town hack [<branch-name>...] [-p | --prototype] [-d | --detached] [-c | --commit] [-m | --message <message>] [--propose] [--dry-run] [-v | --verbose]

The hack command (“let’s start hacking”) creates a new feature branch with the given name off the main branch and brings all uncommitted changes over to it.

Consider this stack:


main
 \
  branch-1
   \
*   branch-2

We are on the branch-2 branch. After running git hack branch-3, our workspace contains these branches:


main
 \
  branch-1
   \
    branch-2
 \
* branch-3

If your Git workspace is clean (no uncommitted changes), it also syncs the main branch to ensure you develop on top of the current state of the repository. If the workspace is not clean (contains uncommitted changes), git town hack does not perform this sync to let you commit your open changes.

Upstream remote

If the repository contains a remote called upstream, it also syncs the main branch with its upstream counterpart. You can control this behavior with the sync-upstream flag.

Positional arguments

When given a non-existing branch name, git town hack creates a new feature branch with the main branch as its parent.

When given an existing contribution, observed, parked, or prototype branch, git town hack converts that branch to a feature branch.

When given no arguments, git town hack converts the current contribution, observed, parked, or prototype branch into a feature branch.

Options

`-p`
`--prototype`

Adding the --prototype aka -p switch creates a prototype branch.

`-d`
`--detached`

The --detached aka -d flag does not pull updates from the main or perennial branch. This allows you to build out your stack and decide when to pull in changes from other developers.

`-c`
`--commit`

When given, commits the currently staged changes into the branch to create and remains on the current branch. This is intended to quickly commit changes unrelated to the current branch into another branch and keep hacking on the current branch. Committing suppresses all branch updates to allow you to get your open changes committed.

`-b`
`--beam`

Moves (“beams”) one or more commits from the current branch to the new feature branch that gets created. Lets you select the commits to beam via a visual dialog. Beaming suppresses all branch updates. Any merge conflicts encountered while beaming arise from moving the beamed commits.

`-m`
`--message`

Commit message to use together with --commit. Implies --commit.

`--propose`

Propose the created branch.

To always propose new branches, set the share new branches setting to propose.

`--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.

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

Configuration

If share-new-branches is configured, git town hack creates a remote tracking branch for the new feature branch. This behavior is disabled by default to make git town hack run fast. The first run of git town sync will create the remote tracking branch.

If the configuration setting new-branch-type is set, git town hack creates a branch with the given type.

git town sync


git town sync [-a | --all] [--no-push] [-s | --stack] [-d | --detached] [-p | --prune] [--dry-run] [-v | --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.

Why does Git Town 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.

Options

`-a`
`--all`

By default this command syncs only the current branch. The --all aka -a parameter makes Git Town sync all local branches.

`--no-push`

The --no-push argument disables all pushes of local commits to their tracking branch.

`-s`
`--stack`

The --stack aka -s parameter makes Git Town sync all branches in the stack that the current branch belongs to.

`-d`
`--detached`

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.

`-p`
`--prune`

The --prune aka -p flag removes (prunes) empty branches, i.e. branches that effectively don’t make any changes.

`--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.

`-v`
`--verbose`

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 development remote.

git town switch


git town switch [<branch-name-regex>...] [-a | --all] [-d | --display-types] [-m | --merge] [-t <name> | --type <name>] [-v | --verbose]

The switch command displays the branch hierarchy on your machine and allows switching the current Git workspace to another local Git branch using VIM motion commands. It can filter the list of branches to particular branch types and regular expression matches.

git town switch reminds you about uncommitted changes in your workspace in case you forgot to commit them to the current branch.

Positional arguments

git town switch interprets all positional arguments as regular expressions. When receiving regular expressions from the user, it displays only the branches that match at least one of the regular expressions.

As an example, assuming all your branches start with me-, you can use this command to switch to one of them:


git town switch me-

To display all branches starting with me- and the main branch:


git town switch me- main

Options

`-a`
`--all`

The --all aka -a flag also displays both local and remote branches.

`-d`
`--display-types`

When enabled, this command displays the types for all branches except the main branch and feature branches.

`-m`
`--merge`

The --merge aka -m flag has the same effect as the git checkout -m flag.

`-t <name>`
`--type <name>`

The --type aka -t flag reduces the list of branches to those that have the given type(s). For example, to display only observed branches:

Switch to one of your observed branches:


git town switch --type=observed

Branch types can be shortened:


git town switch -t o

This can be further compacted to:


git town switch -to

You can provide multiple branch types separated by ,, +, &, or |, like this:


git town switch --type=observed+contribution

This can be shortened to:


git town switch -to+c

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town propose


git town propose [-b <text> | --body <text>] [-f <path> | --body-file <path>] [-t <text> | --title <text>] [-d | --detached] [--dry-run] [-v | --verbose]

The propose command helps create a new pull request (also known as merge request) for the current feature branch. It opens your forge’s website to create a new proposal in your browser and pre-populates information like branch and source/target repository. It also syncs the branch to merge before opening the pull request in detached mode.

Proposing prototype and parked branches makes them feature branches.

You can create pull requests for repositories hosted on:

On non-Windows systems, Git Town will first read the BROWSER environment variable to determine the browser command. If it isn’t set, Git Town will try various common commands like open, xdg-open, or x-www-browser.

Options

`-b <text>`
`--body <text>`

Pre-populate the body of the pull request with the given text.

`-f <path>`
`--body-file <path>`

When called with the --body-file aka -f flag, it pre-populates the body of the pull request with the content of the given file. The filename - reads the body text from STDIN.

`-t <text>`
`--title <text>`

When called with the --title <title> aka -t flag, the propose command pre-populate the title of the pull request to the given text.

`-s`
`--stack`

The --stack aka -s parameter makes Git Town propose all branches in the stack that the current branch belongs to.

`--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.

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

Configuration

You can configure the forge type with the hosting-platform setting.

When using SSH identities, this command uses the hostname in the hosting-origin-hostname setting.

Error handling

Sometimes Git Town commands encounter problems that require the human user to make a decision. When this happens, the command stops and prints an error message. When you have resolved the issue, you can either:

run git town continue to continue executing the interrupted command, starting with the operation that failed,
run git town undo to undo the Git Town command and go back to where you started.

You can also run git town undo after a Git Town command finished to undo the changes it made. Run git town status to see the status of the running Git Town command and which Git Town commands you can run to continue or undo it.

git town continue


git town continue [-v | --verbose]

When a Git Town command encounters a problem that it cannot resolve, for example a merge conflict, it stops to give the user an opportunity to resolve the issue. Once you have resolved the issue, run the continue command to tell Git Town to continue executing the failed command. Git Town will retry the failed operation and execute all remaining operations of the original command.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town skip


git town skip [-v | --verbose]

The skip command allows to skip a Git branch with merge conflicts when syncing all feature branches.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town status


git town status [-p | --pending] [-v | --verbose]
git town status reset [-v | --verbose]

The status command indicates whether Git Town has encountered a merge conflict and which commands you can run to continue, skip, or undo it.

Subcommands

The reset subcommand deletes the persisted runstate. This is only needed if the runstate is corrupted and causes Git Town to crash.

The show subcommand displays detailed information about the persisted runstate.

Options

`-p`
`--pending`

The --pending aka -p argument causes this command to output only the name of the pending Git Town command if one exists. This allows displaying a reminder to run git town continue into your shell prompt when you encountered a merge conflict earlier. See here on how to set this up

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town status reset


git town status reset [-v | --verbose]

The status reset command deletes the persisted runstate. This is only needed if the runstate is corrupted and causes Git Town to crash.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town status show


git town status show [-v | --verbose]

The status show command displays detailed information from Git Town’s persisted runstate, including its path on the filesystem.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town undo


git town undo [-v | --verbose]

The undo command reverts the last fully executed Git Town command. It performs the opposite activities that the last command did and leaves your repository in the state it was before you ran the problematic command.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

Stacked changes

Stacked changes implement and review a complex change as a series of smaller feature branches that build on top of each other. Benefits of stacked changes are:

developer and reviewer maintain momentum and block less on each other
breaking up the problem of developing/reviewing a complex problem into developing/reviewing many smaller problems
minimize merge conflicts by shipping parts of a complex change that are already approved separately from parts still under review

The single responsibility principle applies to feature branches the same way it applies to functions, classes, and methods. Feature branches should also perform only one change. Implementing, refactoring, reviewing, and resolving merge conflicts on such single-responsibility branches is easier than with branches that combine unrelated changes.

Git Town provides wide reaching support for stacked changes. When using stacked changes, try to fast-forward your feature branches into the main branch to avoid empty merge conflicts when syncing the stack later. On GitLab that’s straightforward. GitHub does not provide a fast-forward merge option out of the box but you can achieve it with the fast-forward ship strategy together with the compress or rebase sync strategy. The Git Town GitHub Action adds a visual description of which branch of the stack the pull request is for.

Example

Let’s say we want to add a new feature to an existing codebase. Before we can do that cleanly, we need to get the code base ready:

Make the architecture more flexible so that we can add the new feature in a clean way.
Clean up some technical drift: improve the names of variables and functions.
Build the feature on top of this modernized codebase

Implementing all these changes in a single feature branch is risky. Some changes like the refactor in (1) touch a lot of files that other people might change as well. We want to review and merge them as fast as possible to minimize merge conflicts. Other changes like building the actual feature in (3) will take a while to build. We should therefore make both changes in separate branches. At the same time, the feature (3) depends on the changes in (1) and (2) and drives the changes in (2). We want to develop these changes together. The solution is a stack of feature branches.

Branch 1: refactor

The first feature branch contains the refactor. We create a feature branch named 1-refactor off the main branch to contain it.


git town hack 1-refactor

git town hack creates a new feature branch off the main branch. We perform the refactor and commit it.

Branch 2: rename foo

With the refactored architecture in place, we can update the names of some variables, functions, and files whose role has changed as the code base has evolved. Since these changes require the refactor, we perform them on top of branch 1-refactor:


git town append 2-rename-foo

git town append creates a new feature branch on top of the currently checked out branch (which is 1-refactor). We now have this lineage:


main
 \
  1-refactor
   \
*   2-rename-foo

Branch 2-rename-foo builds on top of 1-refactor and thereby contains all the changes made there. We commit the changes that rename the foo variable. Because we used git town append to create the new branch, Git Town knows about the lineage and creates the proposal (aka pull request) for branch 2-rename-foo against branch 1-refactor. This way, the proposal for branch 2-rename-foo shows only the changes made in that branch (renaming the variable) and not the refactor made in branch 1.

Branch 3: rename bar

This is a different change from renaming foo and has different reviewers. Let’s perform it in a different branch. Some of these changes might happen on the same lines on which we also renamed foo earlier. We don’t want to deal with merge conflicts coming from that. So let’s make this change on top of the change we made in step 2:


git town append 3-rename-bar

The lineage is now:


main
 \
  1-refactor
   \
    2-rename-foo
     \
*     3-rename-bar

Extend the refactoring

While renaming bar, we discover another improvement for the architecture. Let’s add it to the refactoring branch.


git checkout 1-refactor
# make the changes and commit them
git checkout 3-rename-bar

Back on branch 3-rename-bar, the additional refactor we just added isn’t visible because the commit for it exists only in branch 1-refactor right now. Let’s propagate these changes through the entire branch chain so that they become visible in branches 2 and 3 as well:


git town sync

Because we created the branches with git town append, Git Town knows about the branch lineage and git town sync can update all branches in the right order. It updates the main branch, merges main into branch 1. Then it merges branch 1 into branch 2 and branch 2 into branch 3.

Shipping the refactor

We got the approval for the refactor from step 1. Let’s ship it!


git town ship 1-refactor

You have to use the git town ship command here because it updates the lineage that Git Town keeps track of. With branch 1-refactor shipped, our lineage now looks like this:


main
 \
  2-rename-foo
   \
*   3-rename-bar

If you ship feature branches through the API or UI of your forge, run git town sync --all, or git town sync on the youngest child branch, to update the lineage.

Synchronizing our work with the rest of the world

We have been at it for a while. Other developers on the team have made changes to the codebase as well. We don’t want our branches to deviate too much from the main branch since that leads to more severe merge conflicts later. Let’s get all our branches in sync with the rest of the world!


git town sync --all

This pulls updates for the main branch, then merges it into 2-rename-foo, then 2-rename-foo into 3-rename-bar.

Branch 4: building the new feature

We can now add the new feature on top of the code base we prepared:


git town append 4-add-feature

Let’s stop here and review what we have done.

Each change happens in its own feature branch.
Our feature branches build on top of each other and see changes in their parent branches.
We review and ship each feature branch in the chain in isolation.
git town hack creates a feature branch as a child of the main branch.
git town append creates a feature branch as a child of the current feature branch.
git town sync keeps a feature branch chain up to date with the rest of the world
git town ship ships the oldest feature branch in a branch chain.

Single-responsibility branches are easier to reason about and faster to implement, debug, review, and ship than branches performing multiple changes. They encounter fewer and smaller merge conflicts which are easier to resolve than merge conflicts on branches that implement many different changes. You can review and ship parts of your complex change before the entire change is finished. You can still make different changes in parallel, just commit them to the correct branch.

Best practices

One change per branch

When you have an idea that is different from what you currently work on, resist the urge to code it in the current feature branch. Implement it in its own feature, parent, or child branch.

If you can’t create a new branch right now, write the idea down and implement it later.

Keep the stack in sync

Stacks are more susceptible to phantom merge conflicts than stand-alone branches. Don’t forget to populate changes across all branches in your stack by running git town sync --stack or git town sync --all.

Avoid unnecessary stacking

To reduce merge conflicts, feature branches should not diverge too much from the main development branch. Stacking multiple changes on top of each other amplifies this divergence. Overly “tall” stacks are therefore an anti-pattern to avoid. It’s often better to work in independent top-level feature branches by default, and only stack branches if the changes they contain really depend on each other. This way you can get your changes reviewed and shipped concurrently and in any order, i.e. faster and with fewer merge conflicts.

Organize branch chains in the order you want to ship

You always have to ship the oldest branch first. You can use git town prepend to insert a feature branch as a parent of the current feature branch or set parent to change the order of branches.

Avoid phantom merge conflicts

To eliminate phantom merge conflicts after shipping the oldest branch in a stacked change, ship using a fast-forward merge. This guarantees that the new commit(s) on the main branch are the exact same commit(s) from the shipped feature branch. This helps Git recognize those commits at the next git town sync operation and omit unnecessary merge and rebase operations.

GitLab provides fast-forward merges out of the box. GitHub doesn’t provide this out-of-the-box, but allows a workaround that you can utilize by using git town ship with the fast-forward shipping strategy. This problem is documented by GitHub.

You might want to compress the feature branch to have only one new commit on the main branch.

git town append


git town append <branch-name> [-p | --prototype] [-d | --detached] [-c | --commit] [-m | --message <message>] [--propose] [--dry-run] [-v | --verbose]

The append command creates a new feature branch with the given name as a direct child of the current branch and brings over all uncommitted changes to the new branch.

Consider this stack:


main
 \
* feature-1

We are on the feature-1 branch. After running git town append feature-2, the repository will have this stack:


main
 \
  feature-1
   \
*   feature-2

If your Git workspace is clean (no uncommitted changes), it also syncs the current branch to ensure your work in the new branch happens on top of the current state of the repository. If the workspace contains uncommitted changes, git town append does not perform this sync to let you commit your open changes first and then sync manually.

Positional argument

When given a non-existing branch name, git town append creates a new feature branch with the main branch as its parent.

Options

`-p`
`--prototype`

Adding the --prototype aka -p switch creates a prototype branch.

`-d`
`--detached`

The --detached aka -d flag does not pull updates from the main or perennial branch. This allows you to build out your stack and decide when to pull in changes from other developers.

`-c`
`--commit`

`-b`
`--beam`

Moves (“beams”) one or more commits from the current branch to the new child branch that gets created. Lets you select the commits to beam via a visual dialog. Beaming suppresses all branch updates. Any merge conflicts encountered while beaming arise from moving the beamed commits.

`-m`
`--message`

Commit message to use together with --commit. Implies --commit.

`--propose`

Propose the created branch.

To always propose new branches, set the share new branches setting to propose.

`--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.

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

Configuration

If share-new-branches is configured, git town append also creates the tracking branch for the new feature branch. This behavior is disabled by default to make git town append run fast and save CI runs. The first run of git town sync will create the remote tracking branch.

If the configuration setting new-branch-type is set, git town append creates a branch with the given type.

git town detach


git town detach [--dry-run] [-v | --verbose]

The detach command removes the current branch from the stack it is in and makes it a stand-alone top-level branch that ships directly into your main branch.

Consider this stack:


main
 \
  branch-1
   \
*   branch-2
     \
      branch-3

We are on the branch-2 branch. After running git town detach, we end up with with stack:


main
 \
  branch-1
   \
    branch-3
 \
* branch-2

This is useful when a branch in a stack makes changes that are independent from the changes made by other branches in this stack. Detaching such independent branches removes “noise” from your stack, i.e. reduces it to changes that belong together, and allows you to get more of your changes reviewed and shipped concurrently.

Please ensure all affected branches are in sync before running this command, and remove merge commits by compressing.

Options

`--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.

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town diff-parent


git town diff-parent [-v | --verbose]

The diff-parent command displays the changes made on a feature branch, i.e. the diff between the current branch and its parent branch.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town merge


git town merge [--dry-run] [-v | --verbose]

The merge command merges the current branch with the branch ahead of it in the current stack.

Consider this stack:


main
 \
  branch-1
   \
    branch-2
     \
*     branch-3
       \
        branch-4

We are on the branch-3 branch. After running git town merge, the stack looks like below, and the new branch-3 branch contains the changes from the old branch-2 and branch-3 branches.


main
 \
  branch-1
   \
*   branch-3
     \
      branch-4

Both branches must be in sync; run git town sync before running git town merge. All affected branches must be owned by you, i.e. not be contribution, observed, or perennial branches.

When using the compress sync strategy, the merged branch will contain two separate commits: one per merged branch. This makes it easy to verify that both branches were merged as expected. To consolidate these commits, run git town sync.

Options

`--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.

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town prepend


git town prepend [<branch-name>...] [-b | --beam] [--body <string>] [--propose] [-p | --prototype] [-t <text> | --title <text>] [-d | --detached] [-c | --commit] [-m | --message <message>] [--dry-run] [-v | --verbose]

The prepend command creates a new feature branch as the parent of the current branch. It does that by inserting the new feature branch between the current feature branch and it’s existing parent.

Consider this stack:


main
 \
* feature-2

We are on the feature-2 branch. After running git town prepend feature-1, our repository has this stack:


main
 \
* feature-1
   \
    feature-2

If your Git workspace is clean (no uncommitted changes), it also syncs the current feature branch to ensure you work on top of the current state of the repository. If the workspace is not clean (contains uncommitted changes), git town prepend does not perform this sync to let you commit your open changes.

If the branch you call this command from has a proposal, this command updates it. To do so, it pushes the new branch.

Options

`--body <string>`

Pre-populate the body of the pull request to create with the given text. Requires --propose.

`--propose`

Propose the created branch.

To always propose new branches, set the share new branches setting to propose.

`-p`
`--prototype`

Adding the --prototype aka -p switch creates a prototype branch.

`-t <text>`
`--title <text>`

Pre-populate the title of the pull request to create with the given text. Requires --propose.

`-d`
`--detached`

The --detached aka -d flag does not pull updates from the main or perennial branch. This allows you to build out your stack and decide when to pull in changes from other developers.

`-c`
`--commit`

`-b`
`--beam`

Moves (“beams”) one or more commits from the current branch to the new parent branch that gets created. Lets you select the commits to beam via a visual dialog. Beaming suppresses all branch updates. Any merge conflicts encountered while beaming arise from moving the beamed commits.

`-m`
`--message`

Commit message to use together with --commit. Implies --commit.

`--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.

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

Configuration

If the configuration setting new-branch-type is set, git town prepend creates a branch with the given type.

git town set-parent


git town set-parent [<branch>] [-v | --verbose]

The set-parent command changes the parent branch for the current branch. Consider this stack:


main
 \
  feature-1
   \
*   feature-B
 \
  feature-A

After running git town set-parent and selecting feature-A in the dialog, we end up with this stack:


main
 \
  feature-1
 \
  feature-A
   \
*   feature-B

Since set-parent changes commits, your branches must be in sync when running this command. Run git town sync before running git town set-parent.

After set-parent runs, the affected branches no longer contain changes made by their old parents. However, they don’t see the changes made by their new parent branches yet. Please run git town sync to pull in changes from the new parents.

Positional argument

You can provide the name of the new parent for the current branch as an argument to this command. When called without arguments, queries the user for the new parent.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town swap


git town swap [--dry-run] [-v | --verbose]

The swap command switches the position of the current branch with the branch ahead of it in the current stack, i.e. moves the current branch one position forward in the stack.

Consider this stack:


main
 \
  branch-1
   \
*   branch-2
     \
      branch-3

After running git town swap on the branch-2 branch, you end up with this stack:


main
 \
  branch-2
   \
*   branch-1
     \
      branch-3

Moving branches up and down the stack allows you to organize related branches together, for example to review and ship them as a series, or to merge them.

Please ensure that all affected branches are in sync and don’t contain merge commits before running this command, by running git town sync and optionally git town compress before. All affected branches must be owned by you, i.e. you cannot swap contribution, observed, or perennial branches.

Options

`--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.

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

Branch types

Git Town supports many different types of Git branches. Branch types affect how branches are getting synced. When properly configured, you can run git town sync or git town 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. The main branch contains the latest development version of your codebase.

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 of 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 town 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. Deleting 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 town contribute on it. Convert a contribution branch back to a feature branch by running git town hack on it. You can also define a contribution-regex in your Git configuration or the config file.

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, delete only deletes your local copy and not the tracking branch, git town 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 town 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 town observe on it. Convert an observed branch back to a feature branch by running git town hack on it. You can also define an observed-regex in your Git configuration or the config file.

Parked branches

Parked branches don’t get synced at all unless you run git town 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 town park on it. Unpark a parked branch by running git town 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 unless it has a tracking branch. 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. When you park a prototype branch or change it into an observed or contribution branch, it loses its prototype status.

To designate any feature branch as a prototype branch, run git town prototype. To convert a prototype branch to a feature branch, run git town hack.

Configuring branch types

You can set the types of indivdiual branches with these commands:

These preferences allow you to configure the types of larger groups of branches:

git town contribute


git town contribute [<branch-name>...] [-v | --verbose]

The contribute command makes some of your branches contribution branches.

When called without arguments, it makes the current branch a contribution branch.

To convert a contribution branch back into a feature branch, use the hack command.

To make the current branch a contribution branch:


git town contribute

Positional arguments

When called with positional arguments, this commands makes the branches with the given names contribution branches.

To make branches “alpha” and “beta” contribution branches:


git town contribute alpha beta

Check out a remote branch (that exists at the development remote but not on your local machine) and make it a contribution branch:


git town contribute somebody-elses-branch

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town observe


git town observe [<branch-name>...] [-v | --verbose]

The observe command makes some of your branches observed branches.

To convert an observed branch back into a feature branch, use the hack command.

Positional arguments

Observe the current branch:


git town observe

Observe branches “alpha” and “beta”:


git town observe alpha beta

Check out a remote branch (that exists at the development remote but not on your local machine) and make it observed:


git town observe somebody-elses-branch

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town park


git town park [<branch-name>...] [-v | --verbose]

The park command parks some of your branches.

To convert a parked branch back into a feature branch, use the hack command or propose it.

Positional arguments

Park the current branch:


git town park

Park branches “alpha” and “beta”:


git town park alpha beta

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town prototype


git town prototype [<branch-name>...] [-v | --verbose]

The prototype command marks some of your branches as prototype branches.

To convert a prototype branch back into a feature branch, use the hack command.

Positional arguments

Make the current branch a prototype branch:


git town prototype

Make branches “alpha” and “beta” prototype branches:


git town prototype alpha beta

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

Configuration commands

Git Town prompts for required configuration information during usage. Git Town stores its configuration data inside Git configuration data. You can store configuration values in the local or global Git configuration depending on whether you want to share config settings between repositories or not. To see your entire Git configuration, run git config -l. To see only the Git Town configuration entries, run git config --get-regexp git-town. The following commands read and write the configuration entries for you so that you don’t have to run Git configuration commands manually:

git town config - display or update your Git Town configuration
git town config setup - setup assistant for all config settings
git town offline - enable/disable offline mode
git town config sync-perennial-strategy - display or set the strategy to update perennial branches
git town config sync-feature-strategy - display or set the strategy to sync via merges or rebases

git town completions


git town completions (bash|fish|powershell|zsh) [--no-descriptions]

The completions command outputs shell scripts that enable auto-completion for Git Town in Bash, Fish, PowerShell, or Zsh. When set up, typing git-town <tab key> in your terminal will auto-complete subcommands.

Bash

To load autocompletion for Bash, run this command:


source <(git-town completions bash)

To load completions for each session, add the above line to your .bashrc.

Fish

To load autocompletions for Fish, run this command:


git-town completions fish | source

To load completions for each session, add the above line to your ~/.config/fish/config.fish.

PowerShell

To install autocompletions for PowerShell, run this command:


git-town completions powershell | Out-String | Invoke-Expression

To load completions for each session, add the above line to your PowerShell profile.

Zsh

To load autocompletions for Zsh, run this command:


source <(git-town completions zsh)

To load completions for each session, add the above line to your .zshrc.

To fix the error message command not found: compdef, run


autoload -Uz compinit

Options

`--no-descriptions`

The --no-descriptions flag outputs shorter completions without descriptions of arguments.

git town config


git town config [-v | --verbose]
git town config get-parent [<branch-name>] [-v | --verbose]
git town config remove [-v | --verbose]
git town config setup [-v | --verbose]

The config command displays and updates the local Git Town configuration.

Subcommands

Running without a subcommand shows the current Git Town configuration.

The get-parent subcommand outputs the parent branch of the current or given branch.
The remove subcommand removes all Git Town related configuration from the current Git repository.
The setup subcommand launches Git Town’s setup assistant.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town config get-parent


git town config get-parent [<branch-name>] [-v | --verbose]

The config get-parent command outputs the parent branch of the current or given branch.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town config remove


git town config remove [-v | --verbose]

The config remove command removes all Git Town related configuration from the current Git repository.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town config setup


git town config setup [-v | --verbose]

The config setup command launches Git Town’s setup assistant. The setup assistant walks you through all configuration options for Git Town and gives you a chance to adjust them.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town offline


git town offline [<status>] [-v | --verbose]

The offline configuration command displays or changes Git Town’s offline mode. Git Town skips all network operations in offline mode.

Positional arguments

When called without an argument, the offline command displays the current offline status.

When called with yes, 1, on, or true, this command enables offline mode. When called with no, 0, off, or false, it disables offline mode.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

Additional commands

These Git Town commands allow handling edge cases beyond of the basic development workflow outlined earlier.

git town delete - delete a feature branch
git town rename - rename a branch
git town repo - view the Git repository in the browser

git town branch


git town branch [-v | --verbose]

The branch command is Git Town’s equivalent of the git branch command. It displays the local branch hierarchy, and the types of all branches except for main and feature branches.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town compress


git town compress [-m <text> | --message <text>] [-s | --stack] [--dry-run] [-v | --verbose]

The compress command squashes all commits on a branch into a single commit.

Assuming you have a feature branch with these commits:


$ git log --format='%s'
commit 1
commit 2
commit 3

Let’s compress these three commits into a single commit:


git town compress

Now your branch has a single commit with the name of the first commit but containing the changes of all three commits that existed on the branch before:


$ git log --format='%s'
commit 1

Git Town compresses feature branches and parked branches. It doesn’t compress perennial, observed, and contribution branches.

Branches must be in sync to compress them; run git town sync before running this command.

Options

`-m <text>`
`--message <text>`

By default the now compressed commit uses the commit message of the first commit in the branch. You can provide a custom commit message for the squashed commit with the --message <message> aka -m flag, which works similar to the -m flag for git commit.

Assuming you have a feature branch with these commits:


$ git log --format='%s'
commit 1
commit 2
commit 3

Let’s compress these three commits into a single commit:


git town compress -m "compressed commit"

Now your branch has these commits:


$ git log --format='%s'
compressed commit

The new compressed commit now contains the changes from the old commit 1, commit 2, and commit 3.

`-s`
`--stack`

To compress all branches in a stack provide the --stack aka -s switch.

If you want to compress your commits every time you sync, choose the compress sync strategy for the respective branch type.

Assuming you have a stacked change consisting of two feature branches. Each branch contains three commits.


main
 \
  branch-1
  |  * commit 1a
  |  * commit 1b
  |  * commit 1c
  branch-2
     * commit 2a
     * commit 2b
     * commit 2c

Let’s compress the commits in all branches of this stack:


git town compress --stack

Now your stack contains these branches and commits:


main
 \
  branch-1
  |  * commit 1a
  branch-2
     * commit 2a

As usual, the new commit 1a contains the changes made in branch 1, i.e. the changes from the old commit 1a, commit 1b, and commit 1c. The new commit 2a contains the changes made in branch 2, i.e. the changes from the old commit 2a, commit 2b, and commit 2c.

`--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.

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town delete


git town delete [<branch-name>...] [-v | --verbose]

The delete command deletes the given branch from the local and if possible the remote repository, removes commits of deleted branches from their descendents (unless when using the merge sync strategy), and updates proposals of child branches to the parent of the deleted branch.

Consider this stack:


main
 \
  branch-1
   \
*   branch-2
     \
      branch-3

We are on the branch-2 branch. After running git town delete we end up with this stack, on the branch that was active before we switched to branch-2:


main
 \
  branch-1
   \
    branch-3

Git Town deletes only the parts of the branch that you own. If you delete feature, parked, or prototype, it deletes the local and tracking branch. When deleting contribution, observed, or perennial, it deletes only the local branch because you don’t own the tracking branch.

Positional arguments

When called without arguments, the delete command deletes the feature branch you are on, including all uncommitted changes.

When called with a branch name, it deletes the given branch.

Example

Options

`--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.

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town help


git town help

The help command displays detailed information about each Git Town command.

git town rename


git town rename [<old-name>] <new-name> [-f | --force] [--dry-run] [-v | --verbose]

The rename command renames the current branch and its tracking branch. The branch to rename must be fully synced. Updates all affected proposals.

Please be aware that most forges are unable to update the head branch (aka source branch) of proposals. If you rename a branch that already has a proposal, the existing proposal will most likely end up closed and you have to create a new proposal that supersedes the old one. If that happens, Git Town will notify you. Updating proposals of child branches usually works.

Positional arguments

When called with only one argument, the rename command renames the current branch to the given name.

When called with two arguments, it renames the branch with the given name to the given name.

Options

`-f`
`--force`

Renaming perennial branches requires confirmation with the --force aka -f flag.

`--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.

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

git town repo


git town repo [<remote-name>] [-v | --verbose]

The repo command (“show me the repository”) opens the homepage of the current repository in your browser. Git Town can display repositories hosted on GitHub, GitLab, Gitea, Bitbucket, and Codeberg.

Positional arguments

When called without arguments, the repo command shows the repository at the development remote.

When called with an argument, it shows the repository at the remote with the given name.

Options

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

Configuration

Git Town automatically identifies the forge type through the URL of the development remote. You can override the type of hosting server with the hosting-platform setting.

Set the hosting-origin-hostname setting to tell Git Town about the hostname when using ssh identities.

git town ship


git town ship [<branch-name>] [-m <text> | --message <text>] [-s <name> | --strategy <name>] [-p | --to-parent] [--dry-run] [-v | --verbose]

Notice: Most people don’t need to use this command. The recommended way to merge your feature branches is to use the web UI or merge queue of your code hosting service, as you would normally do. git town ship is for edge cases like developing in offline mode or when shipping stacked changes.

The ship command (“let’s ship this feature”) merges a completed feature branch into the main branch and removes the feature branch.

The branch to ship must be in sync. If it isn’t in sync, git town ship will exit with an error. When that happens, run git town sync to get the branch in sync, re-test and re-review the updated branch, and then run git town ship again.

Positional argument

When called without a positional argument, the ship command ships the current branch.

When called with a positional argument, it ships the branch with the given name.

Options

`-m <text>`
`--message <text>`

Similar to git commit, the --message <message> aka -m parameter allows specifying the commit message via the CLI.

`-s <name>`
`--strategy <name>`

Overrides the configured ship-strategy.

`-p`
`--to-parent`

The ship command ships only direct children of the main branch. To ship a child branch, you need to first ship or delete all its ancestor branches. If you really want to ship into a non-perennial branch, you can override the protection against that with the --to-parent aka -p option.

`--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.

`-v`
`--verbose`

The --verbose aka -v flag prints all Git commands run under the hood to determine the repository state.

Configuration

The configured ship-strategy determines how the ship command merges branches. When shipping stacked changes, use the fast-forward ship strategy to avoid empty merge conflicts.

If you have configured the API tokens for GitHub, GitLab, Gitea, Bitbucket, or Codeberg and the branch to be shipped has an open proposal, this command merges the proposal for the current branch.

If your forge automatically deletes shipped branches, for example GitHub’s feature to automatically delete head branches, you can disable deleting remote branches.

Git Town configuration file

Git Town can be configured through a configuration file named .git-town.toml or .git-branches.toml. To create one, run:


git town config setup

Here is an example configuration file with the default settings:


[branches]
main = "" # must be set by the user
contribution-regex = ""
default-type = "feature"
feature-regex = ""
observed-regex = ""
perennial-regex = ""
perennials = []

[create]
new-branch-type = "feature"
share-new-branches = "no"

[hosting]
dev-remote = "origin"
origin-hostname = "" # use the hostname in the origin URL
forge-type = "" # auto-detect

[ship]
delete-tracking-branch = true
strategy = "api"

[sync]
feature-strategy = "merge"
perennial-strategy = "rebase"
push-hook = true
tags = true
upstream = true

[sync-strategy]
prototype-branches = "merge"

Preferences

You can see all preferences via the config command and change them via the setup assistant or manually. Configuration data exists on multiple levels:

Team-wide configuration settings go into the configuration file. These settings apply to all Git Town users working on the respective repository.
Each developer can configure their preferred Git Town settings for all repositories on their machine using global Git metadata. These settings override (1). For example, if I always want to use the rebase sync-feature-strategy in all my repositories, I would run:
```
git config --global git-town.sync-feature-strategy rebase
```
User and repo specific configuration settings go into local Git metadata, which takes precedence over (1) and (2). For example, if I want rebase as the default strategy for all my repositories, except in the foo repo I want to use merge, I’d first configure the global setting in (2), and then run in the foo repo:
```
git config git-town.sync-feature-strategy merge
```

Contribution regex

Branches matching this regular expression are treated as contribution branches.

configure in config file

Setting the contribution regex in the config file is only useful when the matching branches should be considered contribution by all team members. This is typically the case for branches generated by external services, like Renovate or Dependabot.


[branches]
contribution-regex = "^renovate/"

configure in Git metadata

To manually set the contribution regex, run this command:


git config [--global] git-town.contribution-regex '^renovate/'

The optional --global flag applies this setting to all Git repositories on your local machine. When not present, the setting applies to the current repo.

Default branch type

This setting defines the default branch type for Git Town when the branch type is unknown. It applies to branches not listed in main-branch, perennial-branches, contribution-branches, observed-branches, parked-branches, or prototype-branches.

Possible values are:

feature (default)
contribution
observed
parked
prototype

If you set this to anything other than feature, you must also configure the feature-regex setting. Otherwise, there will be no feature branches.

configuration via setup assistant

A great way to configure this setting is through the setup assistant.

configure in config file

In the config file, the default branch type is specified in the [branches] section:


[branches]
default-type = "feature"

configure in Git metadata

You can manually configure the default branch type using Git metadata:


git config [--global] git-town.default-branch-type "feature"

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Feature regex

Branches matching this regular expression are treated as feature branches. This setting is relevant only when the default-branch-type setting is set to something different than “feature”.

configure in config file

In the config file, define the feature regex within the [branches] section:


[branches]
feature-regex = "^my-*"

configure in Git metadata

To manually set the feature regex, use the following command:


git config [--global] git-town.feature-regex '^user-.*'

The optional --global flag applies this setting to all Git repositories on your local machine. When not present, the setting applies to the current repo.

Main branch

This setting stores the name of the main branch. The main branch is the default parent branch for new feature branches created with git town hack and the default branch into which Git Town ships finished feature branches.

config file

In the config file the main branch is part of the [branches] section:


[branches]
main = "config-main"

Git metadata

To configure the main branch in Git, run this command:


git config [--global] git-town.main-branch <value>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Observed regex

Branches matching this regular expression are treated as observed branches.

configure in config file

Setting the observed regex in the config file is only useful when the matching branches should be considered observed by all team members. This is typically the case for branches generated by external services, like Renovate or Dependabot.


[branches]
observed-regex = "^renovate/"

configure in Git metadata

To manually set the feature regex, run this command:


git config [--global] git-town.observed-regex '^renovate/'

The optional --global flag applies this setting to all Git repositories on your local machine. When not present, the setting applies to the current repo.

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.

You can see the configured perennial branches via the config command and change them via the setup assistant.

configure in config file

In the config file the perennial branches are defined as part of the [branches] section:


[branches]
perennials = ["branch", "other-branch"]

configure in Git metadata

You can configure the perennial branches manually by running:


git config [--global] git-town.perennial-branches "branch other-branch"

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

bulk-define perennial branches

If you have many perennial branches that follow the same naming schema, like release-v4.0-rev.1, release-v4.0-rev.2, etc, you can define a regular expression for them instead of listing them one by one.

Perennial regex

All branches matching this regular expression are considered perennial branches.

configure in config file

In the config file the perennial regex exists inside the [branches] section:


[branches]
perennial-regex = "^release-.*"

configure in Git metadata

You can configure the perennial branches manually by running:


git config [--global] git-town.perennial-regex 'release-.*'

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Create prototype branches

This setting is deprecated. Please replace it with the new-branch-type setting.

This setting determines whether Git Town creates new branches as prototype branches.

config file

To configure the creation of prototype branches in the configuration file:


create-prototype-branches = true

Git metadata

To configure the creation of prototype branches manually in Git, run this command:


git config [--global] git-town.create-prototype-branches <true|false>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

New branch type

This setting defines the type for new branches created using the git town hack, append, or prepend commands.

Before setting this, try to configure the branch type using one of these more broadly applicable configuration entries:

values

feature (default)
parked
perennial
prototype

config file

To configure the type of new branches in the configuration file:


new-branch-type = "feature"

Git metadata

To configure the type of new branches in Git metadata, run this command:


git config [--global] git-town.new-branch-type <feature|parked|perennial|prototype>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

This setting allows you to change how Git Town shares new branches created with hack, append, or prepend.

Allowed values:

no: Keep new branches local on your machine until you sync or propose them (default behavior).
push: Push new branches to the development remote.
propose: Create a pull request for the new branch. This is similar to always adding the propose flag.

in config file


create.share-new-branches = "push|propose"

in Git metadata

To enable pushing new branches in Git, run this command:


git config [--global] share-new-branches <push|propose>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, this setting applies to the current Git repo.

Development remote

This setting lets you override the name of the Git remote used for development. This is the remote that branches get pushed to, and into which branches get shipped to. Usually that remote is called origin, which is also the default value for this setting.

config file

To configure the development remote in the configuration file:


[hosting]
dev-remote = "<remote name>"

Git metadata

To configure the development remote manually in Git, run this command:


git config [--global] git-town.dev-remote <remote name>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Forge Type

To talk to the API of your forge, Git Town needs to know which forge type (GitHub, Gitlab, Bitbucket, gitea, Codeberg, etc) you use.

By default, Git Town determines the forge type by looking at the URL of the development remote. If that’s not successful, for example when using a private forge, you can tell Git Town through this configuration setting which forge type you use.

values

You can use one of these values for the forge type setting:

remove the entry or leave it empty for auto-detection
github
gitlab
gitea
bitbucket
bitbucket-datacenter
codeberg

config file

In the config file the forge type is part of the [hosting] section:


[hosting]
forge-type = "<value>"

Git metadata

To configure the forge type in Git, run this command:


git config [--global] git-town.forge-type <value>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, this setting applies to the current Git repo.

Origin hostname

If you use SSH identities, you can define the hostname of your source code repository with this setting. The given value should match the hostname in your SSH config file.

config file

In the config file the forge is part of the [hosting] section:


[hosting]
origin-hostname = "<hostname>"

Git metadata

To configure the origin hostname in Git, run this command:


git config [--global] git-town.hosting-origin-hostname <hostname>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Bitbucket access token

Bitbucket Cloud

Git Town can interact with Bitbucket Cloud in your name, for example to update pull requests as branches get created, shipped, or deleted, or to ship pull requests. To do so, Git Town needs your Bitbucket username and a Bitbucket app password.

An app password is not the password of your Bitbucket account. It’s a special password that you create so that external applications can interact with Bitbucket in your name. To create an app password in the Bitbucket web UI, click on the Settings cogwheel, choose Personal Bitbucket settings, and then in the menu on the left App passwords. You need to enable these permissions:

repository: read and write
pull requests: read and write

Bitbucket Data Center

Git Town can interact with Bitbucket Data Center in your name. To do so, Git Town needs your Bitbucket username and an HTTP access token.

An HTTP access token is not the password of your Bitbucket account. It’s a special password that you create so that external applications can interact with Bitbucket in your name. To create an HTTP access token in the Bitbucket web UI, click on your Profile picture, choose Manage account, and then in the menu on the left HTTP access tokens. You need to enable these permissions:

Project read
Repository write

config file

Since your app password or access token is confidential, you cannot add it to the config file.

Git metadata

You can configure the app password or access token manually by running:


git config [--global] git-town.bitbucket-app-password <token>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Bitbucket username

Git Town can interact with Bitbucket Cloud and Bitbucket Data Center in your name, for example to update pull requests as branches get created, shipped, or deleted. To do so, Git Town needs your Bitbucket username and a Bitbucket app password.

config file

Since usernames are user specific, you cannot add them to the config file.

Git metadata

You can configure the Bitbucket username manually by running:


git config [--global] git-town.bitbucket-username <token>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Codeberg token

Git Town can interact with Codeberg in your name, for example to update pull requests as branches get created, shipped, or deleted. To do so, Git Town needs a personal access token for Codeberg.

To create an API token, follow these steps You need an API token with these permissions:

repository: read and write

config file

Since your API token is confidential, you cannot add it to the config file.

Git metadata

You can configure the API token manually by running:


git config [--global] git-town.codeberg-token <token>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Gitea token

Git Town can interact with Gitea in your name, for example to update pull requests as branches get created, shipped, or deleted. To do so, Git Town needs a personal access token for Gitea.

To create an API token, click on your profile image, choose Settings, and then in the menu on the left Applications. You need an API token with these permissions:

read and write the repository

config file

Since your API token is confidential, you cannot add it to the config file.

Git metadata

You can configure the API token manually by running:


git config [--global] git-town.gitea-token <token>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

GitHub token

Git Town can interact with GitHub in your name, for example to update pull requests as branches get created, shipped, or deleted. To do so, Git Town needs a personal access token with the repo scope. You can create one in your account settings.

config file

Since your API token is confidential, you cannot add it to the config file.

Git metadata

You can configure the API token manually by running:


git config [--global] git-town.github-token <token>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

GitLab token

Git Town can interact with GitLab in your name, for example to update pull requests as branches get created, shipped, or deleted. To do so, Git Town needs a personal access token with api scope. You can create one in your account settings.

config file

Since your API token is confidential, you cannot add it to the config file.

Git metadata

You can configure the API token manually by running:


git config [--global] git-town.gitlab-token <token>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Delete tracking branch

Some forges like GitHub and GitLab can delete the tracking branch when shipping via their API. In this case the tracking branch is already gone when git town ship tries to delete it, resulting in an error. To prevent this error, set this setting to false so that Git Town does not try to delete the tracking branch.

in config file


ship.delete-tracking-branch = true


[ship]
delete-tracking-branch = true

in Git metadata

To configure this setting in Git, run this command:


git config [--global] git-town.ship-delete-tracking-branch <true|false>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Ship strategy

This setting defines how git town ship merges finished feature branches into the main branch.

options

api

When using the “api” ship strategy, git town ship presses the “merge” button for the proposal in the web UI of your forge via an API call.

You need to configure an API token in the setup assistant for this to work.

api is the default value because it does exactly what you normally do manually.

always-merge

The always-merge ship strategy creates a merge commit via git merge --no-ff.

This strategy allows visually grouping related feature commits together which may aid in understanding project history in certain situations.

It is not generally recommended to revert merge commits, so git town undo will not create a merge reversal commit if the merge commit has been pushed already. See howto/revert-a-faulty-merge.txt in the official Git documentation for more information.

fast-forward

The fast-forward ship strategy prevents false merge conflicts when using stacked changes. It merges the branch to ship into its parent (typically the main branch) by running git merge –ff-only and then pushes the new commits on the parent branch to the development remote. This way the parent branch contains the exact same commits as the branch that has just been shipped.

For details why this is needed check out this GitHub documentation.

This works on GitHub even if your main branch is protected as long as the associated proposal is green and has been approved! GitHub recognizes that the commits you push have already been tested and approved and allows them to be pushed. For more information, see this StackOverflow answer.

A limitation of the fast-forward ship strategy is that your feature branch must be up to date, i.e. the main branch must not have received additional commits since you last synced your feature branch.

squash-merge

When set to squash-merge, git town ship merges the feature branch to ship in your local Git repository. While doing so it squashes all commits on the feature branch into a single commit and lets you edit the commit message.

config file

Set the ship strategy in the config file:


ship.strategy = "api"


[ship]
strategy = "api"

Git metadata

To manually configure the ship strategy in Git metadata, run:


git config [--global] git-town.ship-strategy <api|squash-merge>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Feature sync strategy

This setting specifies how to update local feature branches with changes from their parent and tracking branches.

options

merge

When using the “merge” feature sync strategy (which is the default), git town sync merges the parent and tracking branches into local feature branches.

merge is the default value because it is the safest and easiest option.

rebase

When set to rebase, git town sync rebases local feature branches against their parent branches and then does a safe force-push of your rebased local commits to the tracking branch. This safe force-push uses Git’s –force-with-lease and –force-if-includes switches to guarantee that the force-push will never overwrite commits on the tracking branch that haven’t been integrated into the local Git history.

If the safe force-push fails, Git Town rebases your local branch against its tracking branch to pull in new commits from the tracking branch. If that leads to conflicts, you have a chance to resolve them and continue syncing by running git town continue.

When continuing the sync this way, Git Town tries again to safe-force-push and rebase until the safe-force-push succeeds without removing commits from the tracking branch that aren’t part of the local Git history.

This can lead to an infinite loop if you do an interactive rebase that removes commits from the tracking branch while syncing it. You can break out of this infinite loop by doing a less aggressive rebase that doesn’t remove the remote commits. Finish the git town sync command and then clean up your commits via a separate interactive rebase after the sync. At this point another sync will succeed because the commits you have just cleaned up are now a part of your local Git history.

The rule of thumb is that pulling in new commits via git town sync and cleaning up old commits must happen separately from each other. Only then can Git guarantee that the necessary force-push happens without losing commits.

compress

When using the compress sync strategy, git town sync first merges the tracking and parent branches and then compresses the synced branch.

This sync strategy is useful when you want all your pull requests to always consists of only one commit.

Please be aware that this sync strategy leads to more merge conflicts than the “merge” sync strategy when more than one Git user makes commits to the same branch.

config file

In the config file the feature sync strategy is part of the [sync-strategy] section:


[sync]
feature-strategy = "merge"

Git metadata

To manually configure the feature sync strategy in Git, run this command:


git config [--global] git-town.sync-feature-strategy <merge|rebase>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Perennial sync strategy

This setting specifies how to update local perennial branches with changes from their tracking branches.

options

rebase

When using the rebase sync strategy, (which is the default), Git Town rebases local perennial branches onto their tracking branch.

ff-only

Git Town fast-forwards the local branch to match the tracking branch. If a fast-forward is not possible, Git Town exits with a descriptive error message. This is ideal when you want an explicit warning about unpushed local commits.

in config file

In the config file the perennial sync strategy is part of the [sync-strategy] section:


[sync]
perennial-strategy = "rebase"

in Git metadata

To manually configure the perennial sync strategy in Git, run this command:


git config [--global] git-town.sync-perennial-strategy <ff-only|rebase>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Prototype sync strategy

This setting specifies how to update local prototype branches with changes from their parent and tracking branches. When not set, Git Town uses the feature sync strategy.

options

This setting accepts the same options as the feature sync strategy.

config file

In the config file the prototype sync strategy is part of the [sync-strategy] section:


[sync]
prototype-strategy = "merge"

Git metadata

To manually configure the prototype sync strategy in Git, run this command:


git config [--global] git-town.sync-prototype-strategy <merge|rebase>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Run pre-push hook

This setting determines whether Git Town allows or prevents Git hooks while pushing branches. Hooks are enabled by default. If your Git hooks are slow, you can disable them to speed up branch syncing.

When disabled, Git Town pushes using the –no-verify option. This omits the pre-push hook.

config file

To configure running the push hook in the configuration file:


[sync]
push-hook = true

Git metadata

To configure running the push hook manually in Git, run this command:


git config [--global] git-town.push-hook <true|false>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Sync tags

This setting configures whether to sync Git tags with the development remote.

options

When set to true (the default value), git town sync also pulls and pushes Git tags in addition to branches and commits. When set to false, git town sync does not change Git tags at the local or remote Git repository.

in config file

In the config file syncing tags can be set like this:


[sync]
tags = true

in Git metadata

To manually configure syncing tags in Git, run this command:


git config [--global] git-town.sync-tags <true|false>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Sync with upstream

This setting configures whether to pull in updates from the upstream remote. This is intended for codebases that are forks of other codebases and want to stay in sync with the codebase they are forked from.

options

When set to true (the default value), git town sync also updates the local main-branch with changes from its counterpart in the upstream remote. When set to false, git town sync does not pull in updates from upstream even if that remote exists.

in config file

In the config file syncing with upstream can be set like this:


[sync]
upstream = true

in Git metadata

To manually configure syncing with upstream in Git, run this command:


git config [--global] git-town.sync-upstream <true|false>

The optional --global flag applies this setting to all Git repositories on your machine. Without it, the setting applies only to the current repository.

Offline mode

If you have no internet connection, certain Git Town commands that perform network requests will fail. Enabling offline mode omits all network operations and thereby keeps Git Town working.

This setting applies to all repositories on your local machine.

set via CLI

To put Git Town into offline mode, run git town offline.

Git metadata


git config --global git-town.offline <true|false>

Branch lineage

Configuration entries of the form git-town-branch.<branch>.parent=<branch> store the parents of Git branches. You can ignore these configuration entries, Git Town maintains them as it creates and removes feature branches.

Git Town 20.0

How is Git Town different from the git-flow tool?