main
cmd/
docs/
.gitignore
rw-r--r--
25 B
DEVELOPERS.md
rw-r--r--
3.4 KB
README.md
rw-r--r--
5.1 KB
go.mod
rw-r--r--
1.2 KB
go.sum
rw-r--r--
7.0 KB
main.go
rw-r--r--
66 B

Tissue CLI Project Overview

Project Name

Tissue (Terminal Issues)

General Idea

Tissue is a command-line tool designed to manage issue tracking directly within a Git repository, using Markdown files with front matter. Instead of relying on external forges like GitHub or GitLab, Tissue lets you keep all your issues in a dedicated Git branch right alongside your code.

Core Concept

  • Issues as Markdown: Each issue is a Markdown file with front matter (like YAML) for metadata and a body for the description.

  • Dedicated Branch: All issues live in a single “issues” branch, which acts as the single source of truth for issue tracking.

  • Worktree Integration: The “issues” branch can be managed via a Git worktree, ensuring the issues directory is always synced and easily accessible.

Implementation Details

  • Front Matter Structure: Each issue file starts with a YAML front matter block that includes fields like status, priority, tags, and assignee.

  • CLI Commands: Tissue provides commands to list issues, sort them by category or status, and generate an index file (like a README) summarizing current issues.

  • Editing and Updates: When editing issues, the CLI can use the worktree to ensure the user is always working off the latest “issues” branch version. Direct edits are made there and then merged as needed.

Collaboration

  • Multiple Users: Multiple people can work on the “issues” branch, and normal Git merge conflict resolution applies if more than one person edits the same issue file.

Documentation

mdbook serve docs

Usage Examples

Initial Setup

# Initialize tissue in current git repository
tissue init

# Clone a repository and set up tissue branch
git clone https://github.com/user/repo.git
cd repo
tissue init --setup-worktree

Creating Issues

# Create a new issue interactively (prompted metadata, skipable)
tissue new

# Create issue with inline options (skips prompts)
tissue new --title "Fix memory leak in parser" --priority high --tags "bug,performance"

# Push to remote on completion of edit
tissue new --push

# Quick issue creation, editor doesn't open, --push is set to true by default with --quick
tissue new "TODO: Add unit tests for auth module" --quick

Listing and Viewing Issues

# List all issues (default view)
tissue list
tissue ls

# Filter by status
tissue list --status open
tissue list --status closed
tissue list --status "in-progress"

# Filter by multiple criteria
tissue list --priority high --tags bug 

# Sort issues
tissue list --sort priority
tissue list --sort updated --reverse

# Search issues
tissue search "memory leak"
tissue search "auth" --in title,tags
tissue grep "TODO|FIXME" --body-only

Viewing Specific Issues

# View issue by ID, a pretty, table output
tissue 42
tissue issues/042-bad_id.md

# View with different output formats
tissue 42 --format  #(default)
tissue 42 --format json
tissue 42 --raw  # Show raw md file with frontmatter

# Open issue in editor
tissue 42 --edit
tissue 42 -e
tissue 42 --editor vim

Updating Issues

# Update issue status
tissue update 42 --status "in-progress"
tissue close 42
tissue reopen 42

# Update priority and tags
tissue update 42 --priority critical
tissue tag 42 "needs-review" "v2.0"
tissue untag 42 "wontfix"

# Add a comment (timestamped into ### Log section)
tissue comment 42 "Started working on this"

# Start working on an issue
tissue start 42  # Sets status to in-progress, checks out appropriate branch


### Working with Branches and Worktrees

```bash
# Show tissue branch details and status
tissue status

# Sync with remote
tissue pull # alias for git update of issues working tree branch
tissue push # alias for git push into issues working tree branch

Generating Reports

# Generate index/summary
tissue index # default output to issues/README.md
tissue index --output ISSUES.md

Import/Export

# Import from GitHub Issues
tissue import github --repo user/repo
tissue import github --repo user/repo --token $GITHUB_TOKEN

# Import from json
tissue import issues.json

# Export to different formats
tissue export > issues.json

Configuration

# Configure tissue in this project
tissue config editor.default "nvim"
# Configure tissue global
tissue config --global editor.default "nvim"

# List configuration
tissue config --list
tissue config --list --global

Advanced Operations

Integration Examples

See Linking a pull request to an issue using a keyword for the full list of commit keywords

# Git commit integration
git commit -m 'closes #42'
# parses history for keyword issue phrases
# checks for un-matchinig issues in tissue
# proposes updates to the issues 
# could be a good git hook (?)
tissue history 

# CLI integration
tissue complete --shell bash > tissue-completion.bash

Utility Commands

# Help and documentation
tissue --help
tissue new --help

# Version and updates
tissue version