DEVELOPERS.md

This file provides guidance to developers when working with code in this repository.

Project Overview

Tissue (Terminal Issues) is a Go-based CLI tool for managing issue tracking directly within a Git repository using Markdown files with YAML front matter. Issues are stored in a dedicated issues branch managed via Git worktree, providing distributed issue tracking alongside the code.

Architecture

The project follows a standard Go CLI application structure using the Cobra framework:

• main.go: Entry point that calls the cmd package
• cmd/: Contains all CLI command implementations
  • root.go: Root command setup and command registration
  • init.go: Implementation of the tissue init command for repository initialization
• issues/: Git worktree directory for the issues branch (created after tissue init)
• docs/: Documentation using mdBook

Key Dependencies:

• github.com/spf13/cobra: CLI framework for command structure
• github.com/go-git/go-git/v5: Git operations library for repository manipulation
• github.com/go-git/go-billy/v5: Filesystem abstraction for Git operations

Development Commands

Building

# Build with specific output
go build -o bin/tissue

Running

./bin/tissue [command]

Testing

# Run all tests (when tests are added)
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with verbose output
go test -v ./...

Dependencies

# Download dependencies
go mod download

# Tidy dependencies (remove unused, add missing)
go mod tidy

# Verify dependencies
go mod verify

Documentation

# Serve documentation locally (requires mdbook)
mdbook serve docs

# Build documentation
mdbook build docs

Code Patterns

Command Structure

All commands follow the Cobra pattern:

1. Create command function in cmd/ (e.g., NewInitCmd())
2. Define flags in the command creation
3. Implement RunE function for command execution
4. Register command in root.go using cmd.AddCommand()

Error Handling

• Always wrap errors with context using fmt.Errorf("context: %w", err)
• Return errors from RunE functions - Cobra handles exit codes
• Use early returns for error conditions

Git Operations

• Use go-git library for Git operations
• Open repository with git.PlainOpen(".")
• Handle worktrees for the issues branch
• Create orphan branches for issue storage

Issue File Structure

Each issue is a Markdown file in the issues branch with YAML front matter:

---
title: Issue title
status: open|closed|in-progress
priority: low|medium|high|critical
tags: [bug, feature, enhancement]
assignee: username
created: 2024-09-24T10:00:00Z
updated: 2024-09-24T10:00:00Z
---

Issue description in Markdown...

### Log
- 2024-09-24 10:00: Created issue
- 2024-09-24 11:00: Added comment

Implementation Status

Currently implemented:

• Basic CLI structure with Cobra
• tissue init command for repository initialization
  • Creates orphan issues branch
  • Sets up Git worktree in issues directory
  • Creates initial README.md in issues branch

Planned commands (from README):

• tissue new: Create new issues
• tissue list/ls: List and filter issues
• tissue search/grep: Search issues
• tissue update/close/reopen: Modify issue status
• tissue comment: Add timestamped comments
• tissue index: Generate issue summaries
• tissue import/export: Import/export issues
• tissue config: Configuration management