# Git Town — High-Level Git Workflow Automation

> A CLI tool that adds high-level commands to Git for common team workflows like creating feature branches, syncing with upstream, and shipping changes with fewer manual steps.

## Install

Save in your project root:

# Git Town — High-Level Git Workflow Automation

## Quick Use
```bash
# Install via Homebrew
brew install git-town
# Initialize in your repo
git town config setup
# Create a feature branch and start working
git town hack my-feature
# Sync your branch with the main branch
git town sync
```

## Introduction
Git Town adds high-level commands to Git that automate common team workflows. Instead of running multiple git commands to create branches, sync with upstream, and merge changes, Git Town combines these into single commands that handle rebasing, fetching, and branch management automatically.

## What Git Town Does
- Creates feature branches with proper parent tracking via git town hack
- Syncs branches with their parent and upstream via git town sync
- Ships completed features by merging and cleaning up branches
- Manages branch hierarchies for stacked PRs and dependent features
- Handles merge conflicts with a guided resolution workflow

## Architecture Overview
Git Town is a single Go binary that wraps Git commands into higher-level operations. It stores branch metadata (parent relationships, branch types) in Git config. Each command decomposes into a sequence of Git operations executed atomically with undo support. If a conflict occurs mid-operation, Git Town pauses and resumes after manual resolution.

## Self-Hosting & Configuration
- Install via Homebrew, Scoop, AUR, or download prebuilt binaries
- Run git town config setup for interactive repo configuration
- Set the main branch and perennial branches in git config
- Configure sync strategy (rebase or merge) per repository
- Supports both GitHub and GitLab for PR/MR integration

## Key Features
- Atomic multi-step operations with full undo support
- Stacked changes workflow for dependent feature branches
- Offline mode queues sync operations for later execution
- Parking and prototype branch types for work-in-progress management
- Shell completions for Bash, Zsh, Fish, and PowerShell

## Comparison with Similar Tools
- **git-flow** — Prescribes a specific branching model; Git Town is workflow-agnostic and simpler
- **GitHub CLI (gh)** — Manages PRs and issues; Git Town focuses on local branch workflow automation
- **Trunk** — Merge queue service; Git Town handles local development workflow, not CI merging
- **git-branchless** — Focuses on stacked diffs; Git Town covers broader workflow automation

## FAQ
**Q: Does Git Town replace standard Git commands?**
A: No. It adds new commands (git town hack, sync, ship) alongside existing Git commands. Standard Git still works normally.

**Q: Can I undo a Git Town operation?**
A: Yes. git town undo reverts the last Git Town command, restoring branches and commits to their previous state.

**Q: Does Git Town work with monorepos?**
A: Yes. Branch tracking and sync work regardless of repo structure. Configuration is per-repository.

**Q: What happens during a sync conflict?**
A: Git Town pauses the operation, lets you resolve the conflict manually, then run git town continue to finish.

## Sources
- https://github.com/git-town/git-town
- https://www.git-town.com/

---
Source: https://tokrepo.com/en/workflows/asset-24ec7ef7
Author: AI Open Source