How to Use Git Town: The Beginner's Guide (First Install, the init Wizard, First Stacked Branch, and the Ship Arc)

CodexFuse Team · 2026-11-06T15:58:20.496Z · 23 min read min read

How to Use Git Town: The Beginner's Guide (First Install, the init Wizard, First Stacked Branch, and the Ship Arc)

Learning how to use git town takes about an hour the first time, from the install to a shipped stack of branches that reviewers can actually follow. Git Town is a free, open-source command-line tool that adds stacked-branch automation on top of plain Git, and it works with the repository and forge you already use. This git-town tutorial follows the full arc in one guide: install the current release, run the setup wizard, build your first stack, keep it in sync, open pull requests, and ship it.

To use Git Town, install the v24.1.1 binary with your package manager, run git town init once in your repository, create a branch with git town hack, stack more work on top with git town append, keep every branch current with git town sync --all, open a pull request with git town propose, and ship the oldest branch first with git town ship. The sections below walk through each step in order, with the commands exactly as they work in the current release.

All facts in this guide are as of November 2026. CodexFuse offers no Git Town tool, so this guide teaches the open-source project itself, step by step, with every version, command, and limit taken from the official Git Town docs, the GitHub repository, and the release notes. Git Town sits on top of Git, so keep our Git beginner guide open while you follow along.

What Is Git Town?

Git Town is a single self-contained binary that adds high-level Git commands for the work developers repeat all day. The project's own introduction puts it plainly: Git Town solves the problem that using the Git CLI correctly is cumbersome and repetitive. Think of it as your Bash scripts for Git, fully engineered with support for edge cases and error conditions.

Git Town is not a branching model, and it does not replace the workflow your team already uses. Its docs state that it is compatible with GitHub Flow, Git Flow, GitLab Flow, trunk-based development, and even committing straight into the main branch. The tool automates branch creation, syncing, and shipping inside whatever model you already follow.

The core idea is stacked changes: a complex change implemented as a series of smaller, focused feature branches that build on top of each other. Each layer is a real branch with an explicit parent, so reviewers see one small diff at a time instead of a single giant pull request. Git Town keeps those layers in sync, retargets their pull requests when a lower layer ships, and cleans up the branches that are done.

Git Town is a mature project with a long history. The repository was created on 2014-05-15 in GitHub's records, and the current release is v24.1.1, published on 2026-11-06, the same day this guide was written. The release history below shows how quickly the current line has moved.

The numbers below are computed from the GitHub repository data fetched for this guide, and they give a quick sense of the project's scale. The repository holds 3,392 stars and 173 forks, and its open-issues count of 58 includes open pull requests, as GitHub's API counts them together.

stars, forks = 3392, 173
repo_age_days = 4558
v24_0_days_ago = 106
v24_1_days_ago = 41
sheldon_days_ago = 2082
hackernoon_days_ago = 2798
print('stars per fork:', round(stars / forks, 2))
print('fork ratio %:', round(forks / stars * 100, 1))
print('stars per year:', round(stars / (repo_age_days / 365.25), 1))
print('v24.0.0 days ago:', v24_0_days_ago)
print('v24.1.0 days ago:', v24_1_days_ago)
print('Sheldon walkthrough days ago:', sheldon_days_ago)
print('HackerNoon walkthrough days ago:', hackernoon_days_ago)
# stars per fork: 19.61
# fork ratio %: 5.1
# stars per year: 271.8
# v24.0.0 days ago: 106
# v24.1.0 days ago: 41
# Sheldon walkthrough days ago: 2082
# HackerNoon walkthrough days ago: 2798

How to Use Git Town in 7 Steps

Here is the whole arc in seven steps. Each step below has its own section with the details, the flags that matter, and the mistakes to avoid.

1. Install the v24.1.1 binary with your platform's package manager, or with mise through its GitHub backend.
2. Run git town init in your repository and let the setup assistant configure the main branch, the forge, and the sync strategy.
3. Start your first stack with git town hack 1-refactor and commit the foundation change.
4. Stack the next layers with git town append 2-rename-foo and git town append 3-rename-bar.
5. Keep the whole stack current with git town sync --all, and commit into a lower layer with git commit --up=2 when needed.
6. Open a pull request for the current branch with git town propose, which targets the parent branch automatically.
7. Ship the oldest branch first with git town ship, then sync and ship the next layer.

How to Install Git Town

Git Town ships as a single self-contained binary, and it calls the Git executable that is already installed on your machine. Pick the route for your platform from the table below, and do not reach for a Go install: the docs publish no go install route for Git Town.

The docs still say Git Town 24.0 in their header, even though the current release is v24.1.1. That lag is only in the documentation site: the binary you install from Homebrew, the .deb, or the release page is the current patch release. Check the release you got against the v24.1.1 tag on GitHub if you want to be sure.

The mise route deserves one careful note. Git Town is not in mise's core registry, so the bare mise install git-town command does not exist. You must use the GitHub backend form, globally or per project, and you can pin a version in a mise config file instead of taking latest.

mise use -g github:git-town/git-town
# or per project:
mise use github:git-town/git-town
# or in a mise config [tools] section:
# "github:git-town/git-town" = "latest"

Once the binary is on your path, run git town with no arguments to see the command overview. That overview is the fastest way to confirm the install worked, and git town help followed by any command name shows the help for that command. If your repository lives inside a containerized development setup, keep our Docker beginner guide nearby, since the same install commands run inside the container.

The git town init Wizard: Your First-Run Setup

Run git town init the first time you use Git Town in a repository. The command launches an interactive setup assistant that walks you through all configuration options, explains what each one does, lets you adjust them, and validates that everything works.

If your repository already contains a git-town.toml, .git-town.toml, or .git-branches.toml file, you are all set and the wizard has nothing to ask. Otherwise the assistant asks about the main branch, the perennial branches that never ship, the forge you use, and the sync and ship strategies. Answer in plain language: the defaults fit most teams, and you can change every setting later with git town config.

Some features need API access to your forge, so the wizard asks about that too. For GitHub it uses the GitHub CLI or an access token with Git Town's built-in integration; for GitLab it uses the GitLab CLI or a token; Bitbucket needs a username and an API token. API access lets Git Town infer a branch's parent from open pull requests, update pull requests when you rename or reparent branches, and trigger merges from the terminal.

cd your-repo
git town init
# answer the assistant's questions, then verify:
git town config

Do not teach yourself the old manual configuration from pre-2020 guides. The wizard is the current first-run path, and the old guides predate it entirely. If a guide tells you to hand-write Git config keys before your first command, it is describing a Git Town that no longer exists.

Your First Stacked Branch: git town hack

The git town hack command starts a stack by creating its first branch, and it is the entry point to git town stacked branches. It creates a new feature branch off the main branch and brings all uncommitted changes over to it, so you can start work in the middle of something else without stashing by hand.

The command has one behavior worth knowing before you use it daily. If your workspace is clean, hack also syncs the main branch first, so you build on the current state of the repository. If your workspace has uncommitted changes, it skips that sync so you can commit your open changes first.

That split keeps the common case fast and the dirty-workspace case safe.

git town hack 1-refactor
# creates branch 1-refactor off main, carries uncommitted changes over
# implement the refactor, then commit as usual:
git add -A
git commit -m "Extract the shared parser"

Pick branch names that read as a plan, not a mystery. The vendor guide's own example numbers its layers, 1-refactor, then 2-rename-foo, then 3-rename-bar, so the stack order is visible in the branch list. A reviewer who sees those names knows immediately which layer depends on which.

One change per branch is the rule the guide states, and it is the single-responsibility principle applied to feature branches. A layer that does two things cannot be reviewed or shipped independently, which defeats the purpose of stacking. If a layer grows a second job, split it with append instead of stuffing the extra work in.

Building the Stack: git town append and git town prepend

The git town append command extends a stack by adding a branch to its end. Run it while you are on the branch the new work depends on, and Git Town creates the new branch as a direct child of the current one, carrying your uncommitted changes over just like hack does.

git town append 2-rename-foo
# creates branch 2-rename-foo on top of 1-refactor
# do the renames, then commit:
git add -A
git commit -m "Rename foo to bar in the parser"
git town append 3-rename-bar
# creates branch 3-rename-bar on top of 2-rename-foo

When you open a pull request for 2-rename-foo, Git Town targets 1-refactor automatically, so reviewers see only the renames and not the refactor diff underneath. That automatic targeting is the whole payoff of stacking: each pull request shows exactly one layer of change, and the reviewer never has to mentally subtract the layers below it.

Sometimes the missing layer belongs underneath the work you already did. The git town prepend command inserts a new branch between the current branch and its parent, which is how you add a forgotten prerequisite without rebuilding the stack by hand. Prepend takes the same flags as append, including --propose if you want a pull request opened for the new layer right away.

git town prepend 0-setup
# inserts branch 0-setup between main and the current branch

Remember the ordering rule the guide states: you always ship the oldest branch in the stack. A child cannot merge before its parent, because its diff includes the parent's changes. If the oldest layer is not ready, the whole stack waits, which is why keeping stacks short matters.

Keeping the Stack Current: git town sync

The git town sync command updates your local workspace with what happened in the rest of the repository. The docs advise syncing all branches many times per day without thinking about it, even in the middle of ongoing work, and that advice is the habit that makes stacked branches survivable.

Sync pulls and pushes updates from all parent branches and the tracking branch, deletes branches whose tracking branch was deleted at the remote when they hold no unshipped changes, and safely stashes uncommitted changes away and restores them when done. If a sync goes wrong, git town undo takes you back to the exact state your repository was in before the sync.

git town sync --all
# syncs every local branch the right way, deletes shipped branches,
# and pulls main's new commits down through the whole stack

The vendor stacked-changes guide shows sync doing four jobs at once after the first layer ships: it pulls other people's updates into local main, deletes the shipped 1-refactor branch from the local workspace, pulls main's updates into 2-rename-foo, and pulls 2-rename-foo's updates into 3-rename-bar. Then git town append 4-add-feature builds the next layer on the cleaned-up codebase.

Two flags cover the cases where a full sync is too much. Use git town sync --stack when you only want the current stack updated, and use git town sync --all when you want every local branch handled. Stacks are more prone to phantom merge conflicts than standalone branches, so run one of the two regularly to propagate changes across your stacks before the conflicts pile up.

Committing into a lower layer from the top of a stack needs one special command. The git commit --up=2 form commits the staged changes into the branch two layers down, then pulls the updates back up through the layers above it. In the guide's example, staging a fix and running git commit --up=2 lands it in 1-refactor, then syncs 1-refactor into 2-rename-foo and 2-rename-foo into 3-rename-bar.

git add -A
git commit --up=2
# commits the staged changes into 1-refactor, then propagates
# the updates up through 2-rename-foo and 3-rename-bar

Stack Surgery: git town combine, detach, swap, and set-parent

Stacks change shape as the work evolves, and Git Town gives you commands to reshape them without rebuilding branches by hand. The four you will reach for most are combine, detach, swap, and set-parent, plus the navigation commands that move you through a stack.

The git town combine command merges the current branch into the branch ahead of it in the stack, which is how you fold a layer that turned out to be too small into its parent. Note the name: in v24.0.0 the old git town merge command was renamed to git town combine to avoid confusion with git merge. Any guide that still teaches git town merge is describing a command that no longer exists.

git town combine
# merges the current branch into its parent branch in the stack

The git town detach command extracts a branch from a stack and makes it its own independent stack, which is the fix when a layer turns out not to depend on the layers below it. The git town swap command switches the position of the current branch and its parent, and git town set-parent changes the parent of the current branch and all its descendants.

Navigation is part of the same toolkit. The git town branch command shows where you are in the stack hierarchy, git town down switches to the parent branch, git town up switches to the child branch, and git town switch jumps to any branch with a visual dialog. The git town walk command runs a command or opens an interactive shell on each branch of the stack, which is useful for running a test suite across every layer.

Opening a Pull Request: git town propose

The git town propose command creates a pull request for the current feature branch. It opens your forge's website in the browser, pre-populates the branch and the source and target repositories, and syncs the branch before opening the proposal in detached mode. Supported forges are Bitbucket, Forgejo, Gitea, GitHub, and GitLab.

Propose replaced the old git town new-pull-request command, which no longer exists in v24. If a walkthrough from 2019 or 2021 tells you to run git town new-pull-request, translate it to git town propose and keep reading; the rest of that walkthrough's arc is still directionally right, but its command names are stale.

git town propose
# opens the pull request form in your browser, pre-filled
# propose the whole stack at once:
git town propose --stack

The --stack flag opens a pull request for every branch in the stack, each targeted at its parent. That is the moment the stacked workflow pays off visibly: reviewers get a chain of small pull requests instead of one large one, and each one shows only its own layer. If your team reviews on GitHub, keep our GitHub beginner guide open, since the pull request itself lives there.

The Ship Arc: git town ship and the Four Strategies

The git town ship command merges a completed feature branch into the main branch and removes the feature branch. When called without an argument it ships the current branch, and it also accepts a branch name to ship a different one. The branch must be in sync first: if it is not, ship exits with an error, and you run git town sync, re-test and re-review, then ship again.

Here is the framing the vendor docs give, and it matters: most people don't need to use this command, because the recommended way to merge feature branches is the web UI or merge queue of your hosting service. Git Town ship exists for edge cases like developing in offline mode or shipping stacked changes, where merging from the terminal avoids a round of CI runs per layer.

Ship also verifies that your workspace holds no uncommitted changes before it starts, so nothing half-finished gets swept into the merge. Four strategies control how the merge itself happens, and the table below lists them exactly as the docs define them.

The fast-forward strategy is the one the stacked-changes guide recommends for shipping a whole stack. After you merge the proposal for the oldest branch, you normally need to sync to propagate the shipped changes through the rest of the stack, which triggers a CI run for each branch even though the code has not changed. Fast-forward shipping avoids that waste.

git switch 1-refactor
git town ship --strategy=fast-forward
git switch 2-rename-foo
git town ship --strategy=fast-forward

Fast-forward shipping works because no commits are rewritten: only branch pointers move, so downstream branches stay in sync and CI does not re-run. It only works when the stack is in sync with main, meaning main has received no new commits since you last synced. If main moved, a fast-forward is no longer possible, and you must sync the stack again or ship with a different strategy.

Set the strategy once instead of passing the flag every time. You can put [ship] strategy = "fast-forward" in the config file, run git config git-town.ship-strategy fast-forward, or set the GIT_TOWN_SHIP_STRATEGY environment variable. If your team merges through an API token, remember that the API strategy is the default and needs that token configured in the setup assistant.

For the token itself and what an API call is, see our guide on what an API is.

Git Town vs Git Flow, Graphite, spr, and GitHub Stacked PRs

The question git town vs git flow comes up constantly, and the answer is that they are different kinds of thing. Git Flow is a branching convention from Vincent Driessen's 2010 model: a long-lived develop branch beside main, feature branches off develop, release branches for stabilization, and hotfix branches off main. Git Town is automation that runs inside that convention or any other, creating and syncing the branches the convention calls for.

Trunk-based development is the other common comparison, and the same logic applies. In trunk-based work everyone integrates into the trunk at least daily, branches are short-lived, and incomplete work hides behind flags rather than on a branch. Git Town complements that style: stacked branches are short-lived layers that each merge to trunk as soon as they are approved, and the project's docs list trunk-based development among the models it supports.

The stacked-diff tools are closer cousins, and the table below separates them by what each one actually is. Graphite is a commercial hosted review platform whose signature feature is stacked diffs, and Cursor announced its acquisition of Graphite on 2025-12-19, planning to keep it as a standalone product. The spr tool is GitHub-only and turns a series of commits into a stack of pull requests.

GitHub itself shipped native stacked pull requests, generally available on 2026-10-06, with a stack map on each pull request and automatic rebasing when lower layers merge.

GitHub's native stacks deserve a closer look because they are the newest competition for the concept. They are built on standard Git branches and regular pull requests, and GitHub's own docs say you can manage branch chains with another tool such as git-town and open those branches as a stack with gh stack link. The two approaches are complementary, and Git Town predates GitHub's native feature by years.

The standalone gh-stack command-line plugin is a different story: it holds 154 stars and its last push was on 2021-09-09, which is 1,884 days before this guide, so it is effectively unmaintained as a standalone project. GitHub's native feature and its gh stack extension superseded it. When an old article recommends gh-stack, check the date before following it.

When to Stack and When a Single Branch Suffices

Stacking is a tool for dependent changes, not a default for everything. The vendor guide's rule is to only stack changes that depend on each other, and to create independent top-level feature branches off main for everything else. Independent branches can ship in any order, which is a freedom a stack gives up by design.

Stack when a change is too large to review in one pull request and its layers genuinely depend on each other: a refactor, then renames on top of it, then the feature that uses the renamed code. Stack when a reviewer would drown in a single diff but can approve three small ones in sequence. Stack when an early layer is blocked on review but the later work can proceed on top of it.

Do not stack when the pieces are independent, when a single branch already tells the story cleanly, or when the stack would grow past three or four layers. Long stacks turn into long-lived branches, and the guide warns to keep stacks short so they do not become the thing trunk-based teams are trying to avoid. Multiple short stacks beat one tall stack every time.

If you install tools through a version manager, the mise route from the install section is the one to remember. Mise pins tool versions per project, and Git Town installs through its GitHub backend rather than a registry entry. Keep our Mise beginner guide open if you manage your toolchain that way.

Sources

The version numbers, commands, and limits in this guide come from the Git Town documentation at git-town.com, including the install page, the configuration page, the stacked-changes guide, the ship-stack how-to, and the command pages for init, hack, sync, append, prepend, combine, propose, and ship, plus the full command list and the ship-strategy reference in the project's repository. The release dates, star and fork counts, and repository age come from the GitHub API for git-town/git-town and its v24.0.0, v24.1.0, and v24.1.1 release pages, all fetched on 2026-11-06. The stale-walkthrough dates come from Sheldon Hull's 2021 Git Town workflow guide and the 2019 HackerNoon nested-branches article, and the comparison figures come from the GitHub API for spr, gh-stack, and git-revise, GitHub's documentation on using stacked pull requests with other tools, Ajay Kumar's 2026 branching-strategies guide, and the December 2025 Cursor-Graphite acquisition reports from SiliconAngle and TechCrunch.

Frequently Asked Questions

Is Git Town the same as Git Flow?

No. Git Flow is a branching convention from 2010 with develop, release, and hotfix branches, while Git Town is a command-line tool that automates creating, syncing, and shipping branches inside Git Flow or any other model you already use.

Do I need git town ship, or should I merge in the browser?

Merge in the browser or through your merge queue for normal work, because that is what the vendor docs recommend. Use git town ship for edge cases such as developing offline or shipping a whole stack without triggering a CI run for every layer.

How do I install Git Town with mise?

Run mise use -g github:git-town/git-town for a global install or mise use github:git-town/git-town inside a project, because the bare mise install git-town command has no matching entry. You can also pin a version in a mise config file with "github:git-town/git-town" = "latest" or a specific version number.

What changed in Git Town v24?

Version 24.0.0 replaced the old merge command with combine, replaced new-pull-request with propose, moved Bitbucket Cloud to API tokens, and made config redact secrets by default. Version 24.1.0 added the mise install instructions to the website, and v24.1.1 fixed set-parent for parents checked out in another worktree.

Can I use Git Town with GitHub's native stacked pull requests?

Yes. GitHub's native stacked pull requests, generally available on 2026-10-06, are built on standard Git branches, and GitHub's docs say you can open branches managed by git-town as a stack with gh stack link. The two approaches complement each other rather than competing.