Development workflow

Setting up

git clone https://github.com/charmbracelet/bubbletea
cd bubbletea
go mod download

The repo contains three Go modules:

Module path	Location	Purpose
charm.land/bubbletea/v2	repo root	The library
examples (untagged)	examples/	66 self-contained demos
tutorials (untagged)	tutorials/	The annotated grocery-list tutorial

The two sub-modules pull in heavier dependencies (Bubbles, Lip Gloss, Glamour) without inflating the library's own dependency tree.

Daily commands

# Format, vet, and run all linters
task lint

# Run all tests
task test

# Run a specific test
go test ./... -run TestExecCommand

# Race + coverage like CI does
go test -race -covermode=atomic -coverprofile=coverage.txt ./...

# Run an example
cd examples && go run ./list-fancy

Branch hygiene

• Branch off main. Use a short descriptive name; the project does not require a fixed prefix.
• Keep PRs focused. The Charm team prefers smaller, well-scoped changes over sweeping rewrites.
• Rebase rather than merge when bringing your branch up to date.

Editor setup

The project uses gofumpt and goimports. If you are using gopls, add "gopls": { "formatting.gofumpt": true } to your settings so formatting on save matches CI.

Updating tutorials and examples

examples.yml runs an automated go mod tidy for the sub-modules whenever examples/go.mod, tutorials/go.mod, or the root go.mod/go.sum change. The action commits with author actions-user and message chore: go mod tidy tutorials and examples. You usually do not need to run go mod tidy manually for these sub-modules — the automation handles it.

Working with ultraviolet

A lot of low-level work — keyboard parsing, the cell buffer, ANSI helpers — lives in github.com/charmbracelet/ultraviolet. When fixing a bug it is common to reach for a fix in ultraviolet first, then bump the indirect dependency here. The repo has many chore: bump ultraviolet to … commits in git log that show the pattern.