Documentation
¶
Overview ¶
Package internal is the root for git-treeline's domain packages.
Concurrency Model ¶
The codebase uses four distinct concurrency mechanisms. Each is purpose-built to avoid contention at a specific layer.
## 1. Registry file lock (advisory flock, 5s timeout)
All mutations to registry.json acquire an exclusive flock on registry.json.lock. The lock uses a non-blocking retry loop with 100ms polling and a 5-second timeout. This supports concurrent CLI invocations (e.g. two terminals running `gtl setup`) without corrupting the shared state file. Writes use atomic temp+rename.
See: registry.(*Registry).withLock
## 2. Router route table (sync.RWMutex)
The subdomain router holds an in-memory route map protected by RWMutex. A background goroutine refreshes routes from the registry every 2 seconds (read path), while every HTTP request reads the map (hot read path). The write lock is only held during the swap.
See: proxy.Router.mu, proxy.Router.refreshRoutes
## 3. TLS certificate cache (sync.RWMutex)
CertManager caches issued leaf certificates keyed by hostname. Read lock for cache hits; write lock for new issuance. The cache is bounded to 1000 entries to prevent unbounded growth from garbage hostnames. Expired certs are lazily replaced on next access.
See: proxy.CertManager.mu, proxy.CertManager.cache
## 4. Supervisor child lifecycle (sync.Mutex)
The supervisor protects its child process pointer with a mutex. Start/stop/restart operations acquire the lock to prevent races between the Unix socket command handler and signal-driven shutdown.
See: supervisor.Supervisor.mu
## 5. Localhost resolution cache (sync.Map, 5s TTL)
The router probes whether each port is reachable on IPv4 or IPv6 and caches the result for 5 seconds to avoid TCP probes on every proxied request. sync.Map is used because reads vastly outnumber writes and keys are stable (port numbers).
See: proxy.localhostCache, proxy.resolveLocalhost
## What is NOT parallelized (and why)
Setup commands run sequentially. They may have ordering dependencies (e.g. `bundle install` before `rails db:create`). Parallel execution would require explicit dependency declaration in .treeline.yml.
Port allocation is serialized via the registry file lock. The allocator reads all used ports, finds a free block, and writes back atomically. Parallel allocation would require a compare-and-swap protocol that adds complexity for minimal gain (allocation is fast).
`gtl status` runs health checks with a WaitGroup for parallelism but does not limit concurrency. For typical setups (<20 worktrees) this is fine. If worktree counts grow significantly, a semaphore (like golang.org/x/sync/semaphore) would prevent fd exhaustion.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package allocator provides resource allocation for git worktrees.
|
Package allocator provides resource allocation for git worktrees. |
|
Package config handles user and project configuration for git-treeline.
|
Package config handles user and project configuration for git-treeline. |
|
Package confirm provides interactive prompts for CLI commands.
|
Package confirm provides interactive prompts for CLI commands. |
|
Package database provides adapters for database template cloning.
|
Package database provides adapters for database template cloning. |
|
Package dbsource resolves remote PostgreSQL connection details for a configured database source (production, staging, ...).
|
Package dbsource resolves remote PostgreSQL connection details for a configured database source (production, staging, ...). |
|
Package detect provides framework and tooling auto-detection from filesystem signals.
|
Package detect provides framework and tooling auto-detection from filesystem signals. |
|
Package devresources admits the finite, explicitly reserved managed-dev pool.
|
Package devresources admits the finite, explicitly reserved managed-dev pool. |
|
Package doctor holds the pure decision logic behind `gtl doctor`: the request-flow walk that finds the first broken link in the app→router→pf→CA chain, the auto-fix planner that maps findings to remediations, and the port-config classifier.
|
Package doctor holds the pure decision logic behind `gtl doctor`: the request-flow walk that finds the first broken link in the app→router→pf→CA chain, the auto-fix planner that maps findings to remediations, and the port-config classifier. |
|
Package editor provides IDE integration for worktree environments.
|
Package editor provides IDE integration for worktree environments. |
|
Package format provides shared formatting utilities for CLI output and registry allocation field extraction.
|
Package format provides shared formatting utilities for CLI output and registry allocation field extraction. |
|
Package github provides GitHub API integration via the gh CLI.
|
Package github provides GitHub API integration via the gh CLI. |
|
Package interpolation provides template variable substitution for environment files and configuration values.
|
Package interpolation provides template variable substitution for environment files and configuration values. |
|
Package platform provides platform-specific configuration paths.
|
Package platform provides platform-specific configuration paths. |
|
Package process is the single home for discovering and terminating the processes that hold gtl's TCP ports.
|
Package process is the single home for discovering and terminating the processes that hold gtl's TCP ports. |
|
Package provision implements `gtl provision`: the repo-level, idempotent answer to "what must be true on a host before gtl setup can succeed for this repo." It reads the provision: section of .treeline.yml and brings a host up to that declared baseline — system packages, services, language runtimes, and the template database gtl clones worktree databases from.
|
Package provision implements `gtl provision`: the repo-level, idempotent answer to "what must be true on a host before gtl setup can succeed for this repo." It reads the provision: section of .treeline.yml and brings a host up to that declared baseline — system packages, services, language runtimes, and the template database gtl clones worktree databases from. |
|
Package proxy provides a local reverse proxy for forwarding traffic from a stable listen port to a worktree's dynamically allocated port.
|
Package proxy provides a local reverse proxy for forwarding traffic from a stable listen port to a worktree's dynamically allocated port. |
|
Package registry provides persistent allocation state with file locking.
|
Package registry provides persistent allocation state with file locking. |
|
Package resolve provides cross-worktree service discovery.
|
Package resolve provides cross-worktree service discovery. |
|
Package routerdomain validates the DNS suffix used by the local HTTPS router.
|
Package routerdomain validates the DNS suffix used by the local HTTPS router. |
|
Package runtimeowner retains exact runtime ownership and shutdown outcomes.
|
Package runtimeowner retains exact runtime ownership and shutdown outcomes. |
|
Package selfupdate provides the latest-release lookup, version comparison, and on-disk check cache behind 'gtl update' and the passive update notice.
|
Package selfupdate provides the latest-release lookup, version comparison, and on-disk check cache behind 'gtl update' and the passive update notice. |
|
Package service manages the git-treeline router as a system service.
|
Package service manages the git-treeline router as a system service. |
|
Package setup provides worktree provisioning orchestration.
|
Package setup provides worktree provisioning orchestration. |
|
Package share provides private branch sharing via a token-gated reverse proxy fronting a cloudflared tunnel, or via Tailscale Serve for tailnet-only access.
|
Package share provides private branch sharing via a token-gated reverse proxy fronting a cloudflared tunnel, or via Tailscale Serve for tailnet-only access. |
|
Package style provides terminal color styles for CLI output.
|
Package style provides terminal color styles for CLI output. |
|
Package supervisor provides a lightweight process wrapper that runs a command in the foreground while accepting restart/stop signals over a Unix socket.
|
Package supervisor provides a lightweight process wrapper that runs a command in the foreground while accepting restart/stop signals over a Unix socket. |
|
Package tailscale provides helpers for detecting and interacting with the Tailscale CLI.
|
Package tailscale provides helpers for detecting and interacting with the Tailscale CLI. |
|
Package templates provides YAML and agent context generation.
|
Package templates provides YAML and agent context generation. |
|
Package tui implements the gtl dashboard terminal UI.
|
Package tui implements the gtl dashboard terminal UI. |
|
Package tunnel wraps cloudflared to expose local ports via public HTTPS tunnels.
|
Package tunnel wraps cloudflared to expose local ports via public HTTPS tunnels. |
|
Package tunneldaemon implements a lazy-start supervisor that lets multiple `gtl tunnel` invocations share a single cloudflared process for one named tunnel.
|
Package tunneldaemon implements a lazy-start supervisor that lets multiple `gtl tunnel` invocations share a single cloudflared process for one named tunnel. |
|
Package worktree provides git worktree operations including creation, branch detection, and repository inspection.
|
Package worktree provides git worktree operations including creation, branch detection, and repository inspection. |