Skip to content

User Guide

Welcome to the TaskRepo User Guide. This section covers core concepts and workflows for effective task management.

Core Concepts

Tasks

Tasks are the fundamental unit in TaskRepo. Each task is a markdown file with YAML frontmatter containing metadata.

Repositories

Tasks are organized into repositories - git-backed directories containing related tasks. You might have separate repositories for work, personal projects, or different teams.

Task Lifecycle

Tasks move through different states: pending → in-progress → completed or cancelled.

User Guide Topics

Task Management

Learn how to effectively create, organize, and manage your tasks.

  • Creating tasks with all metadata
  • Organizing with projects, tags, and priorities
  • Managing task lifecycle
  • Using links and attachments
  • Task dependencies

Repositories

Understand how to organize tasks across multiple repositories.

  • Creating and managing repositories
  • When to use multiple repositories
  • Repository naming conventions
  • Moving tasks between repositories

Configuration

Customize TaskRepo to match your workflow.

  • Configuration file reference
  • Setting defaults
  • Editor configuration
  • Sort preferences
  • Display options

Search & Filters

Master task discovery and filtering.

  • Text search
  • Advanced filtering
  • Combining filters
  • Saved searches (coming soon)

Quick Tips

Use the TUI

The interactive TUI (tsk tui) provides a visual way to browse and manage tasks

Batch Operations

Most commands support operating on multiple tasks: tsk done 1,2,3

Natural Language Dates

Use natural language for due dates: tomorrow, next week, Nov 15

Git Integration

Remember to sync regularly with tsk sync to share tasks with your team

The Interactive TUI

TaskRepo TUI

The Terminal User Interface (tsk tui) provides a powerful visual way to manage tasks:

  • Keyboard-driven: All operations accessible via keyboard shortcuts
  • Multi-select: Select and operate on multiple tasks at once
  • Real-time details: See full task information in the details panel
  • Color-coded: Visual status and priority indicators
  • Countdown timers: See how much time until tasks are due

Launch with: tsk tui

Best Practices

  1. Use Projects: Group related tasks with the project field
  2. Tag Liberally: Use tags for cross-cutting concerns (bug, urgent, blocked)
  3. Set Due Dates: Add due dates to important tasks
  4. Regular Reviews: Run tsk list regularly to review pending tasks
  5. Sync Often: Keep your team in sync with tsk sync

Workflow Examples

Personal Task Management

tsk create-repo personal
tsk add -r personal -t "Buy groceries" --due tomorrow
tsk add -r personal -t "Call dentist" --tags health

Team Sprint Planning

tsk create-repo sprint-24
tsk add -r sprint-24 -t "Implement user auth" -p backend --assignees @alice --priority H
tsk add -r sprint-24 -t "Design login UI" -p frontend --assignees @bob
tsk sync --repo sprint-24

Bug Tracking

tsk add -r work -t "Fix memory leak" --tags bug,critical --priority H \
  --links https://github.com/org/repo/issues/456

Next Steps