fix(create): say --file is one issue per ## heading (#5921)

bd create --file/-f is a batch-import route: it creates one issue per
H2 ("##") heading, and ### subsections attach fields to that issue.
The old Usage was "Create multiple issues from markdown file", which
never named those semantics or --body-file. Callers who wanted "one
issue, description loaded from a file" reached for the shortest flag
and got a silent bulk import instead -- reported by @seanmartinsmith
with a 3-section briefing file (## Problem / ## Context / ##
Acceptance Criteria) that became 3 issues instead of one.

gatherCreateInput already rejects a positional title combined with
--file. That is the reporter's literal repro, so this keeps the
rejection and adds a --body-file hint on the error they actually
see. The remaining trap -- --file used alone on a section-headed
file -- is unchanged, because bd cannot tell that apart from a
genuine batch file by content.

Tests: parseMarkdownFile reproduces the trap file; gatherCreateInput
locks in the title+--file rejection and --body-file hint; flag Usage
names the per-heading behavior. The existing TestCreateFromMarkdownFile
binary path already covers well-formed --file creates.
This commit is contained in:
Vishnu J 2026-09-02 18:11:56 -07:00 • committed by GitHub
commit 67b066b58e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 107 additions and 2 deletions

View file

@ -895,7 +895,7 @@ func createDepsAcceptedTypeList() string {
}
func init() {
createCmd.Flags().StringP("file", "f", "", "Create multiple issues from markdown file")
createCmd.Flags().StringP("file", "f", "", "Create one issue per ## heading (### fields attach to that issue); for title plus description-from-file, use --body-file")
createCmd.Flags().String("graph", "", "Create a graph of issues with dependencies from JSON plan file")
createCmd.Flags().String("title", "", "Issue title (alternative to positional argument)")
createCmd.Flags().Bool("silent", false, "Output only the issue ID (for scripting)")

View file

@ -171,3 +171,46 @@ func TestCreateSingleIssueAllowEmptyDescriptionRoundTrip(t *testing.T) {
t.Fatalf("expected issue %q to be created via --allow-empty-description opt-in", title)
}
}
// TestCreateFileDispatchRejectsPositionalTitle is a regression test for
// gastownhall/beads#4643: --file is a batch-import route, so a positional
// title has nowhere to go once createIssuesFromMarkdown takes over. This
// asserts gatherCreateInput's existing guard still rejects the combination
// before any issue is written, rather than silently discarding the title.
func TestCreateFileDispatchRejectsPositionalTitle(t *testing.T) {
saveAndRestoreGlobals(t)
ensureCleanGlobalState(t)
readonlyMode = false
t.Cleanup(func() { readonlyMode = false })
fileFlag := createCmd.Flags().Lookup("file")
t.Cleanup(func() {
_ = fileFlag.Value.Set("")
fileFlag.Changed = false
})
tmpDir := t.TempDir()
mdPath := filepath.Join(tmpDir, "single.md")
if err := os.WriteFile(mdPath, []byte("## My Bead\n\nBody text.\n"), 0644); err != nil {
t.Fatalf("write markdown fixture: %v", err)
}
if err := createCmd.Flags().Set("file", mdPath); err != nil {
t.Fatalf("set --file: %v", err)
}
var err error
stderr := captureStderr(t, func() {
err = createCmd.RunE(createCmd, []string{"my new bead"})
})
if err == nil {
t.Fatal("expected --file dispatch with a positional title to be rejected")
}
if !strings.Contains(stderr, "cannot specify both title and --file flag") {
t.Fatalf("expected title/--file conflict message on stderr, got: %v (err: %v)", stderr, err)
}
if !strings.Contains(stderr, "--body-file") {
t.Fatalf("expected title/--file conflict to hint at --body-file, got: %v (err: %v)", stderr, err)
}
}

View file

@ -95,7 +95,7 @@ func gatherCreateInput(cmd *cobra.Command, args []string) (createInput, error) {
}
if in.markdownFile != "" {
if len(args) > 0 {
return in, HandleError("cannot specify both title and --file flag")
return in, HandleError("cannot specify both title and --file flag; for a single issue's description from a file, use --body-file")
}
if in.dryRun {
return in, HandleError("--dry-run is not supported with --file flag")

View file

@ -40,6 +40,36 @@ func TestCreateCommandRegistersEmptyDescriptionOptIn(t *testing.T) {
}
}
func TestCreateFileFlagHelpDoesNotClaimSingleIssueGH4643(t *testing.T) {
f := createCmd.Flags().Lookup("file")
if f == nil {
t.Fatal("expected create to register --file")
}
if !strings.Contains(f.Usage, "one issue per") {
t.Fatalf("expected --file help text to name its per-heading batch behavior, got: %q", f.Usage)
}
if !strings.Contains(f.Usage, "--body-file") {
t.Fatalf("expected --file help text to point single-issue callers at --body-file, got: %q", f.Usage)
}
}
func TestGatherCreateInputRejectsTitleWithFile(t *testing.T) {
cmd := newCreateFlagsCommand(t, "--file", "issues.md")
var err error
stderr := captureStderr(t, func() {
_, err = gatherCreateInput(cmd, []string{"Some title"})
})
if err == nil {
t.Fatal("expected gatherCreateInput to reject a positional title with --file")
}
if !strings.Contains(stderr, "cannot specify both title and --file flag") {
t.Fatalf("expected title/--file conflict on stderr, got stderr=%q err=%v", stderr, err)
}
if !strings.Contains(stderr, "--body-file") {
t.Fatalf("expected title/--file conflict to hint at --body-file, got stderr=%q err=%v", stderr, err)
}
}
func TestGatherCreateInputRejectsEmptyBodyFile(t *testing.T) {
filePath := filepath.Join(t.TempDir(), "empty.md")
if err := os.WriteFile(filePath, nil, 0644); err != nil {

View file

@ -154,6 +154,38 @@ Just a title and description.
},
},
},
{
name: "GH-4643 H2-per-section briefing file parses as three issues",
content: `## Problem
Something is broken.
## Context
Extra background.
## Acceptance Criteria
It should work.
`,
expected: []*IssueTemplate{
{
Title: "Problem",
Description: "Something is broken.",
Priority: 2,
IssueType: "task",
},
{
Title: "Context",
Description: "Extra background.",
Priority: 2,
IssueType: "task",
},
{
Title: "Acceptance Criteria",
Description: "It should work.",
Priority: 2,
IssueType: "task",
},
},
},
}
for _, tt := range tests {