@pleaseai/gh-please-docs
Features

Issue Management

Manage GitHub issues with types, sub-issues, dependencies, and development workflow

Issue Management

Comprehensive issue management features including issue types, hierarchical relationships, dependencies, and development workflow.

Issue Types

Manage GitHub issue types to categorize and organize your issues effectively.

Create Issue with Type

gh please issue create --title "Issue title" [--body "description"] [--type "Type Name"] [--type-id "Node ID"]

Examples:

# Create issue with type (by name)
gh please issue create --title "Login fails on Safari" --type Bug

# Create issue with type (by Node ID)
gh please issue create --title "Add dark mode" --type-id "IT_kwDO..."

# Create with JSON output
gh please issue create --title "Performance issue" --type Bug --json number,title,url,type

List Available Types

gh please issue type list [--json [fields]]

Examples:

# Human-readable format (default)
gh please issue type list

# JSON for automation
gh please issue type list --json

# Select specific fields
gh please issue type list --json name,color,description

Set/Update Issue Type

gh please issue type set <issue-number> --type "Type Name"
# or
gh please issue type set <issue-number> --type-id "Node ID"

Examples:

# Set type by name
gh please issue type set 123 --type Feature

# Set type by Node ID
gh please issue type set 123 --type-id "IT_kwDO..."

# Cross-repository
gh please issue type set 123 --type Bug --repo owner/repo

Remove Issue Type

gh please issue type remove <issue-number>

Example:

gh please issue type remove 123

Sub-Issues

Create hierarchical issue structures to break down large tasks.

Create New Sub-Issue

gh please issue sub-issue create <parent-issue> --title "Sub-task title" [--body "description"]

Example:

gh please issue sub-issue create 100 --title "Add input validation" --body "Validate user inputs"

Link Existing Issue

gh please issue sub-issue add <parent-issue> <child-issue>

Example:

# Link issue #101 as sub-issue of #100
gh please issue sub-issue add 100 101

List Sub-Issues

gh please issue sub-issue list <parent-issue> [--format json|markdown|xml]

Output formats:

  • json - Machine-readable JSON
  • markdown - Human-readable Markdown (default)
  • xml - Structured XML for LLM processing

Example:

gh please issue sub-issue list 100
gh please issue sub-issue list 100 --format json

Remove Sub-Issue

gh please issue sub-issue remove <parent-issue> <child-issue>

Dependencies

Manage issue dependencies with "blocked by" relationships.

Add Blocker

gh please issue dependency add <issue> --blocked-by <blocker>

Example:

# Mark issue #200 as blocked by #199
gh please issue dependency add 200 --blocked-by 199

List Blockers

gh please issue dependency list <issue> [--format json|markdown|xml]

Remove Dependency

gh please issue dependency remove <issue> <blocker>

Development Workflow

Start working on issues with automatic branch and worktree management.

Start Development (Worktree Mode)

Creates an isolated workspace in ~/.please/worktrees/{repo}/{branch}:

gh please issue develop <issue-number> [options]
# Alias: gh please issue dev

Options:

  • --base <branch> - Base branch (default: main)
  • --name <branch> - Custom branch name
  • --repo owner/repo - Target repository
  • --worktree - Explicitly enable worktree mode (default)

Example:

# Create worktree for issue #123
gh please issue develop 123

# With custom base branch
gh please issue develop 123 --base develop

# From outside git repo
gh please issue develop 123 --repo owner/repo

Workflow:

  1. Checks if bare repo exists at ~/.please/repositories/{owner}/{repo}.git
  2. If not, prompts to clone as bare repository
  3. Creates worktree at ~/.please/worktrees/{repo}/{branch}
  4. Links branch to issue via gh issue develop

Start Development (Checkout Mode)

Checkout branch in current repository instead of creating worktree:

gh please issue develop <issue-number> --checkout

Requirements:

  • Must be in a git repository
  • Works like traditional branch checkout

Example:

gh please issue dev 123 --checkout

Cleanup Worktrees

Remove unused worktrees interactively or in batch:

gh please issue cleanup [--all] [--repo owner/repo]

Options:

  • --all - Remove all prunable worktrees without prompt
  • --repo - Target repository

Example:

# Interactive cleanup
gh please issue cleanup

# Batch removal
gh please issue cleanup --all

# From outside repo
gh please issue cleanup --repo owner/repo

Comment Management

List Comments

gh please issue comment list <issue-number> [--format json|markdown|xml]

Example:

gh please issue comment list 123
gh please issue comment list 123 --format json

Edit Comment

gh please issue comment edit <comment-id> --body "Updated text"

Example:

gh please issue comment edit 987654321 --body "Corrected information"

Common Options

All issue commands support:

  • --repo owner/repo or -R owner/repo - Target different repository
  • --format json|markdown|xml - Output format (list commands only)

Related

Quick Start

Get up and running with gh-please in 5 minutes

PR Management

Manage pull request reviews, threads, and comments efficiently