Developer Setup Guide

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• README.md
• install.sh
• internal/cli/init.go
• internal/config/config.go
• tests/e2e_test.go

This guide provides instructions for setting up a development environment for Docktree, a Go-based CLI tool designed to coordinate Docker Compose services across multiple git worktrees. It covers prerequisites, installation, project structure, and local development workflows.

Sources: CONTRIBUTING.md:1-5, README.md:1-5

Prerequisites

Before contributing to Docktree, ensure the following tools are installed on your system:

• Go: Version 1.25 as pinned in go.mod.
• Docker: Must include the Compose plugin (docker compose) for end-to-end testing.
• Just: (Optional) A task runner used for automating build and test sequences.
• Git: Required for worktree management and repository detection.

Sources: CONTRIBUTING.md:27-33, install.sh:31-48

Installation and Initial Setup

For Users

Users can install Docktree using the provided shell script or Homebrew:

# Shell script installation
curl -fsSL https://raw.githubusercontent.com/Bnjoroge1/docktree/main/install.sh | sh

# Homebrew installation
brew tap Bnjoroge1/tap
brew install docktree

Sources: README.md:11-20, install.sh:1-12

For Developers

To set up the repository for local development:

1. Clone the repository:

   git clone https://github.com/Bnjoroge1/Docktree.git
   cd Docktree
   

2. Download dependencies:

   go mod download
   

Sources: CONTRIBUTING.md:35-39

Project Architecture and Layout

Docktree is structured as a standard Go CLI application. The following table describes the primary directories:

Directory	Description
cmd/docktree/	The main entry point for the CLI application.
internal/	Core library code, including compose handling, port allocation, and CLI logic.
tests/	Integration and end-to-end (E2E) tests.
testdata/	Static fixtures used during testing.
Formula/	Homebrew formula for distribution.

Sources: CONTRIBUTING.md:41-48

Development Workflow

The following diagram illustrates the typical developer workflow from building to testing:

This flow ensures that code is functional, tested, and adheres to linting standards before submission.
Sources: CONTRIBUTING.md:50-74

Building and Testing

Build Commands

Developers can use just or standard Go commands to build the binary:

• Build: just build or go build ./cmd/docktree
• Install: just install (installs to GOPATH/bin)
• Run without install: just run -- [args] or go run ./cmd/docktree [args]

Sources: CONTRIBUTING.md:50-59

Testing Guidelines

Docktree relies on unit and integration tests. The CI environment specifically runs race-enabled tests.

• Unit Tests: just test (runs tests in ./internal/...)
• All Tests: just test-all
• CI Emulation: go test -race -count=1 ./...

Note: Developers should use fixtures in testdata/ and avoid adding mocks where a real fixture can be used.
Sources: CONTRIBUTING.md:61-74, tests/e2e_test.go:10-25

Linting and Formatting

The project uses golangci-lint and go vet to maintain code quality:

just fmt    # gofmt -w .
just lint   # go vet ./...
golangci-lint run # full suite

Sources: CONTRIBUTING.md:76-84

Project Configuration

Docktree can be configured using a docktree.yml file. If not present, the system uses default values.

Default Configuration Values

Option	Path	Default Value
Port Range	ports.range	41000-49999
Bind Host	ports.bind_host	127.0.0.1
State Dir	state.directory	.docktree
Setup Copy	setup.copy	[.env]
Setup Symlink	setup.symlink	[node_modules]

Sources: internal/config/config.go:119-146

Configuration Initialization

Developers can generate a starting configuration by scanning existing Docker Compose files:

docktree init --json --dry-run

The init command detects "shareable" services (like Postgres or Redis) and proposes a configuration that handles tenancy and environment variable rewriting.
Sources: internal/cli/init.go:50-80, internal/cli/init.go:167-200

Contribution Guidelines

• Branch Policy: main is protected. All changes must go through a Pull Request and require approval from the code owner (@Bnjoroge1).
• Commit Style: Use imperative subjects (e.g., "Add port range override") under 72 characters.
• CI Requirements: Build, vet, test, and lint checks must pass before merging.

Sources: CONTRIBUTING.md:88-115

Docktree provides a robust environment for managing isolated Docker stacks across git worktrees, ensuring that developers and AI agents can work in parallel without resource collisions.
Sources: README.md:5-10