clarify --issues + --parent flag interaction in selective sync (#3056)

Follow-up to #2957 and #2975. The two flags were silently ANDed in the
engine (IssueIDs filter first, then descendantSet filter), which would
only sync issues appearing in both sets — confusing and likely wrong.

Fix: applySelectiveSyncFlags now returns an error when both flags are
set, documenting them as mutually exclusive. Updated flag descriptions
and added TestIssuesAndParentAreMutuallyExclusive to prove the rejection.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
matt wilkie 2026-04-06 09:37:47 -07:00 • committed by GitHub
commit 7fb50921b6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 47 additions and 5 deletions

View file

@ -8,20 +8,35 @@ import (
)
// registerSelectiveSyncFlags adds --issues and --parent flags to a tracker sync command.
// These two flags are mutually exclusive: use --issues to sync specific beads by ID,
// or --parent to sync an entire subtree. Combining them is an error.
func registerSelectiveSyncFlags(cmd *cobra.Command) {
cmd.Flags().String("issues", "", "Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def)")
cmd.Flags().String("issues", "", "Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.")
if cmd.Flags().Lookup("parent") == nil {
cmd.Flags().String("parent", "", "Limit push to this bead and its descendants")
cmd.Flags().String("parent", "", "Limit push to this bead and its descendants (push only). Mutually exclusive with --issues.")
}
}
// applySelectiveSyncFlags parses --issues and --parent from cmd and applies them to opts.
// Returns an error if --parent is used without push.
//
// Rules:
// - --parent requires push mode (incompatible with --pull-only).
// - --issues and --parent are mutually exclusive: --issues targets specific beads by ID
// while --parent scopes by subtree. Combining them would produce confusing AND semantics
// (only issues that are BOTH in the ID list AND in the subtree would be synced).
// To sync a subtree plus additional individual issues, use --issues with all desired IDs.
func applySelectiveSyncFlags(cmd *cobra.Command, opts *tracker.SyncOptions, push bool) error {
if issuesFlag, _ := cmd.Flags().GetString("issues"); issuesFlag != "" {
issuesFlag, _ := cmd.Flags().GetString("issues")
parentID, _ := cmd.Flags().GetString("parent")
if issuesFlag != "" && parentID != "" {
return fmt.Errorf("--issues and --parent are mutually exclusive: use --issues to target specific beads by ID, or --parent to sync a subtree")
}
if issuesFlag != "" {
opts.IssueIDs = splitCSV(issuesFlag)
}
if parentID, _ := cmd.Flags().GetString("parent"); parentID != "" {
if parentID != "" {
if !push {
return fmt.Errorf("--parent requires push (cannot use with --pull-only)")
}

View file

@ -4,6 +4,7 @@ import (
"testing"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/tracker"
)
// TestParentFlagRegistered verifies --parent flag exists on all tracker sync commands.
@ -47,3 +48,29 @@ func TestParentFlagNotOnNotion(t *testing.T) {
t.Log("Notion sync has --parent flag (may be intentional for future use)")
}
}
// TestIssuesAndParentAreMutuallyExclusive verifies that specifying both --issues
// and --parent on the same sync command returns an error.
//
// The two flags cannot be combined: --issues targets specific bead IDs while
// --parent scopes by subtree. Silently ANDing them would produce confusing
// results where only issues that appear in both sets are synced.
func TestIssuesAndParentAreMutuallyExclusive(t *testing.T) {
t.Parallel()
cmd := &cobra.Command{Use: "test"}
registerSelectiveSyncFlags(cmd)
if err := cmd.Flags().Set("issues", "bd-123"); err != nil {
t.Fatalf("setting --issues: %v", err)
}
if err := cmd.Flags().Set("parent", "bd-456"); err != nil {
t.Fatalf("setting --parent: %v", err)
}
var opts tracker.SyncOptions
err := applySelectiveSyncFlags(cmd, &opts, true /* push */)
if err == nil {
t.Fatal("expected error when both --issues and --parent are set, got nil")
}
}