Skip to main content
TaskGraph now supports moving tasks between different tag contexts, allowing you to organize your work across multiple project contexts, feature branches, or development phases.

Overview

Cross-tag task movement enables you to:
  • Move tasks between different tag contexts (e.g., from “backlog” to “in-progress”)
  • Handle cross-tag dependencies intelligently
  • Maintain task relationships across different contexts
  • Organize work across multiple project phases

Basic Usage

Within-Tag Moves

Move tasks within the same tag context:

Cross-Tag Moves

Move tasks between different tag contexts:

Dependency Resolution

When moving tasks between tags, you may encounter cross-tag dependencies. TaskGraph provides several options to handle these:

Move with Dependencies

Move the main task along with all its dependent tasks:
This ensures that all dependent tasks are moved together, maintaining the task relationships.

Break Dependencies

Break cross-tag dependencies and move only the specified task:
This removes the dependency relationships and moves only the specified task.

Force Move

Note: Force moves are no longer supported. Instead, use one of these options:
  • --with-dependencies — move dependents together
  • --ignore-dependencies — break cross-tag dependencies
⚠️ Warning: This may break dependency relationships and should be used with caution.

Error Handling

TaskGraph provides enhanced error messages with specific resolution suggestions:

Cross-Tag Dependency Conflicts

When you encounter dependency conflicts, you’ll see:

Subtask Movement Restrictions

Subtasks cannot be moved directly between tags:

Invalid Tag Combinations

When source and target tags are the same:

Best Practices

1. Check Dependencies First

Before moving tasks, validate your dependencies:

2. Use Appropriate Flags

  • --with-dependencies: When you want to maintain task relationships
  • --ignore-dependencies: When you want to break cross-tag dependencies

3. Organize by Context

Use tags to organize work by:
  • Development phases: backlog, in-progress, review, done
  • Feature branches: feature-auth, feature-dashboard
  • Team members: alice-tasks, bob-tasks
  • Project versions: v1.0, v2.0

4. Handle Subtasks Properly

For subtasks, either:
  1. Promote the subtask to a full task first
  2. Move the parent task with all subtasks using --with-dependencies

Advanced Usage

Multiple Task Movement

Move multiple tasks at once:

Tag Creation

Target tags are created automatically if they don’t exist:

Current Tag Fallback

If --from-tag is not provided, the current tag is used:

MCP Integration

The cross-tag move functionality is also available through MCP tools:

Troubleshooting

Common Issues

  1. “Source tag not found”: Check available tags with taskgraph tags
  2. “Task not found”: Verify task IDs with taskgraph list
  3. “Cross-tag dependency conflicts”: Use dependency resolution flags
  4. “Cannot move subtask”: Promote subtask first or move parent task

Getting Help

Examples

Scenario 1: Moving from Backlog to In-Progress

Scenario 2: Breaking Dependencies

Scenario 3: Force Move

Choose one of these options explicitly:

Scenario 4: Moving Subtasks