gotodo

A simple, filesystem-aware todo CLI tool written in Go. Manage your todos with colors, Git repository integration, and per-project lists.

Table of Contents

• Features
• Installation
• Usage
• Examples
• Contributing
• License

Features

• ✅ Git-aware: Automatically uses the repository root for todo files when inside a Git repo
• 🎨 Colored output: Beautiful CLI interface with Lipgloss
• 📁 Per-directory/project: Todo lists are scoped to directories or Git repos
• 🔍 Discovery: Commands automatically find the appropriate todo file
• 🛠️ Simple commands: Init, add, list, done, remove with intuitive flags
• 📝 Multi-word tasks: Support for tasks with spaces
• ⚡ Fast: Lightweight and efficient

Installation

Prerequisites

• Go 1.20 or later
• Git (for repository detection)

Install from source

Clone the repository:

git clone https://github.com/juparave/gotodo.git
cd gotodo

Build and install:

go install ./cmd/gotodo

This installs gotodo to your $GOBIN or $GOPATH/bin directory.

Install Latest Release

go install github.com/juparave/gotodo/cmd/gotodo@latest

Install Specific Version

go install github.com/juparave/gotodo/cmd/gotodo@v0.0.2

Manual build

# From repository root
go build -o gotodo ./cmd/gotodo

# Move to PATH (example for macOS/Linux)
sudo mv gotodo /usr/local/bin/

Usage

gotodo uses a .gotodo.json file:

• Inside Git repos: At the repository root
• Outside Git repos: In the current directory

Commands

gotodo <command> [arguments]

Command	Description	Flags
init	Initialize a new todo file	-
add <task>	Add a new todo item	-
list	List all todos	--done-limit, --long, --file
done <id|n>	Mark todo as done (id or open index)	--file
rm <id|n>	Remove a todo (id or open index)	--force, --yes, --file
count	Print the number of todos as a bare integer	--done, --all, --file
help	Show usage (also --help, -h)	-

Global Flags

• --file <path>: Override the default todo file path
• --help, -h: Show usage
• --version, -v: Print the gotodo version

Examples

Basic workflow

# Initialize (only needed once per project/repo)
gotodo init

# Add some todos
gotodo add "Write documentation"
gotodo add "Implement feature X"
gotodo add "Fix bug in parser"

# List todos
gotodo list

# Mark first open todo as done
gotodo done 1

# Remove a todo (with confirmation)
gotodo rm 2

# Force remove without confirmation
gotodo rm 3 --force

# How many are still open?
gotodo count

Advanced usage

# Show only last 5 done todos
gotodo list --done-limit 5

# Show timestamps for done todos
gotodo list --long

# Use a specific file
gotodo list --file /path/to/custom/.gotodo.json

# Work from any subdirectory (Git repo aware)
cd subdir/
gotodo add "Subdir task"  # Adds to repo root .gotodo.json

Shell prompt integration

count prints a single integer and nothing else, so it is safe to call from a prompt or status line. A missing .gotodo.json prints 0 and exits 0.

gotodo count          # open todos (default)
gotodo count --done   # completed todos
gotodo count --all    # every todo

With bash-git-prompt, define a prompt_callback before sourcing gitprompt.sh to show a pending-todo flag next to the git status:

prompt_callback() {
    command -v gotodo >/dev/null 2>&1 || return
    local n
    n=$(gotodo count 2>/dev/null) || return
    [[ $n =~ ^[0-9]+$ ]] && (( n > 0 )) || return
    printf ' %s☐%s%s' "${BoldYellow}" "$n" "${ResetColor}"
}

Sample output

Todos

Open:
  1. Write documentation
  2. Implement feature X

Done:
  1. Fix bug in parser  (2025-09-30 10:30:00)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development

# Clone and setup
git clone https://github.com/juparave/gotodo.git
cd gotodo

# Run tests
go test ./...

# Build
go build ./cmd/gotodo

# Format code
gofmt -s -w .
goimports -w .
go vet ./...

License

This project is licensed under the MIT License - see the LICENSE file for details.