fix(merge-driver): emit merge=text instead of -merge for ignore-derived exclusions (#761)

* fix(merge-driver): emit merge=text for ignore-derived exclusions

The .gitattributes managed block wrote ignore-derived Markdown
exclusions as `-merge`, which unsets git's merge attribute. Per
git-attributes, an unset merge declares a file binary with no
well-defined merge semantics: git takes the current branch and
declares a conflict, so two branches editing different sections of an
ignored Markdown file conflict and cannot auto-resolve.

Markdown has well-defined text-merge semantics, and an ignored path is
never linted, so it carries no generated sections for the mdsmith
driver to reconcile. Emit `merge=text` (git's built-in 3-way text
merge) instead. The mdsmith driver still stays off the path
(last-match-wins over the include lines), and ordinary edits merge
normally.

ExtractGlobs now recognizes both `merge=text` (current) and `-merge`
(legacy) as exclusions, so a .gitattributes written by an older
mdsmith round-trips unchanged and does not read as drift.

The committed .gitattributes is deliberately left in `-merge` form:
the merge queue verifies it with the pinned v0.53.0 baseline via
`ci-install`, which does not yet parse `merge=text`. Regenerating it
is a follow-up gated on bumping that pin, per
docs/development/adopt-new-directive-syntax.md.

Fixes #755

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W8S3VduddQAbq8FPduzFyf

* docs(githooks): sweep last stale -merge reference in scopeExcludeToMarkdown

Code-review follow-up: the merge=text change updated every other
reference, but scopeExcludeToMarkdown's doc comment still said the
already-markdown branch returns "its -merge line". The emitted form is
now merge=text; call it an "exclude line" to match.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W8S3VduddQAbq8FPduzFyf

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jeduden

cmd/mdsmith/mergedriver.go

@@ -36,14 +36,18 @@ Subcommands:
         exclude lines for each ignore pattern (last-match-wins
         overrides). Each ignore pattern is intersected with the
         markdown include extensions, so an ignore of demo/** emits
-        demo/**/*.md -merge and demo/**/*.markdown -merge rather
-        than a bare demo/** -merge that would also disable git's
-        merge for non-markdown files in that tree.
+        demo/**/*.md merge=text and demo/**/*.markdown merge=text
+        rather than a bare demo/** merge=text that would also change
+        git's merge for non-markdown files in that tree. The
+        excludes use merge=text (git's built-in 3-way text merge),
+        not -merge (merge unset): both take the mdsmith driver off
+        the path, but -merge leaves these Markdown files binary-
+        conflicting while merge=text keeps ordinary edits merging.
 
         Optional positional args replace the default include set
         when callers want to scope the merge driver to a custom
         pattern (e.g. docs/**/*.md); .mdsmith.yml ignore
-        patterns still apply on top via -merge overrides. Custom
+        patterns still apply on top via merge=text overrides. Custom
         include globs are not compatible with the MDS048
         git-hook-sync rule's auto-fix, which restores the
         canonical default include set plus ignore-derived
@@ -473,8 +477,8 @@ func hasConflictMarkers(content []byte) bool {
 // (`*.md`, `*.markdown`) is used and the project's .mdsmith.yml
 // `ignore:` patterns become markdown-scoped exclude overrides —
 // each pattern is intersected with the markdown include extensions
-// (see githooks.GlobsFromConfig) so a `-merge` line never disables
-// git's merge for non-markdown files. Patterns that cannot appear
+// (see githooks.GlobsFromConfig) so a `merge=text` line never
+// changes git's merge for non-markdown files. Patterns that cannot appear
 // verbatim in `.gitattributes` (whitespace, leading `!`) are
 // silently dropped by `GlobsFromConfig`. Explicit args replace the
 // include set so callers can scope the merge driver to a custom
@@ -604,7 +608,7 @@ func runMergeDriverCIInstall(args []string) int {
 	// Compute the expected glob set exactly as install would write it,
 	// so the two commands can never disagree on what "in sync" means.
 	// nil args means the canonical default include set plus the
-	// .mdsmith.yml ignore-derived -merge overrides.
+	// .mdsmith.yml ignore-derived merge=text overrides.
 	expected, rc := resolveManagedGlobs(repoRoot, nil)
 	if rc != 0 {
 		return rc

cmd/mdsmith/mergedriver_test.go

@@ -295,7 +295,7 @@ func TestRunMergeDriverInstall_RejectsWhitespacePath(t *testing.T) {
 func TestRunMergeDriverInstall_NoArgsWritesCanonicalGlobs(t *testing.T) {
 	dir := t.TempDir()
 	initTestRepo(t, dir)
-	// .mdsmith.yml ignore patterns become -merge overrides.
+	// .mdsmith.yml ignore patterns become merge=text overrides.
 	require.NoError(t, os.WriteFile(filepath.Join(dir, ".mdsmith.yml"),
 		[]byte("ignore:\n  - \"vendor/**\"\n"), 0o644))
 
@@ -318,12 +318,14 @@ func TestRunMergeDriverInstall_NoArgsWritesCanonicalGlobs(t *testing.T) {
 	content := string(attrs)
 	assert.Contains(t, content, "*.md merge=mdsmith")
 	assert.Contains(t, content, "*.markdown merge=mdsmith")
-	assert.Contains(t, content, "vendor/**/*.md -merge",
-		"ignore patterns from .mdsmith.yml must appear as markdown-scoped -merge overrides")
-	assert.Contains(t, content, "vendor/**/*.markdown -merge",
+	assert.Contains(t, content, "vendor/**/*.md merge=text",
+		"ignore patterns from .mdsmith.yml must appear as markdown-scoped merge=text overrides")
+	assert.Contains(t, content, "vendor/**/*.markdown merge=text",
 		"ignore patterns are scoped to every markdown include extension")
-	assert.NotContains(t, content, "vendor/** -merge",
-		"a bare -merge line would disable git's merge for non-markdown files (issue #750)")
+	assert.NotContains(t, content, "vendor/** merge=text",
+		"a bare exclude line would change git's merge for non-markdown files (issue #750)")
+	assert.NotContains(t, content, "-merge",
+		"excludes use merge=text, not -merge, so ignored Markdown still gets git's text merge (issue #755)")
 }
 
 // --- resolveInstalledBinary ---
@@ -777,9 +779,9 @@ func TestRunMergeDriverInstall_DropsAndWarnsForUnrepresentableIgnore(t *testing.
 	attrs, err := os.ReadFile(filepath.Join(dir, ".gitattributes"))
 	require.NoError(t, err)
 	content := string(attrs)
-	assert.Contains(t, content, "vendor/**/*.md -merge",
+	assert.Contains(t, content, "vendor/**/*.md merge=text",
 		"representable ignore patterns survive, scoped to markdown")
-	assert.Contains(t, content, "vendor/**/*.markdown -merge",
+	assert.Contains(t, content, "vendor/**/*.markdown merge=text",
 		"representable ignore patterns survive, scoped to every markdown extension")
 	assert.NotContains(t, content, "with space.md",
 		"unrepresentable ignore patterns are dropped from the managed block")

docs/reference/cli/merge-driver.md

@@ -23,14 +23,25 @@ Register the merge driver in `git config` and ensure
 `.gitattributes` assigns it. The managed block is derived
 from `.mdsmith.yml`. It lists include patterns first
 (default `*.md` and `*.markdown`). Then it lists one
-`-merge` exclude line per representable `ignore:` pattern.
-Last match wins.
+`merge=text` exclude line per representable `ignore:`
+pattern. Last match wins.
+
+The exclude lines use `merge=text`, git's built-in 3-way
+text merge, not `-merge`. Both take the mdsmith driver off
+the path, but `-merge` unsets the `merge` attribute — which
+declares the file binary and leaves it whole-file-conflicting.
+An ignored path is Markdown that mdsmith never lints, so it
+carries no generated sections for the driver to reconcile;
+`merge=text` keeps ordinary edits merging and avoids that
+class of conflict. A `.gitattributes` written by an older
+mdsmith that still lists `-merge` is read the same way, so
+it does not report as drift until it is regenerated.
 
 Each `ignore:` pattern is scoped to the markdown include
 extensions. So `ignore: ["demo/**"]` emits
-`demo/**/*.md -merge` and `demo/**/*.markdown -merge`. A
-bare `demo/** -merge` is not used. It would also turn off
-git's 3-way merge for the source code in that tree.
+`demo/**/*.md merge=text` and `demo/**/*.markdown merge=text`.
+A bare `demo/** merge=text` is not used. It would also change
+git's merge for the source code in that tree.
 
 Some `ignore:` entries cannot be expressed in
 `.gitattributes`: `!` negation patterns and patterns with

internal/githooks/githooks.go

@@ -170,17 +170,24 @@ const configFileName = ".mdsmith.yml"
 // set's markdown extensions before it becomes an exclude line, so a
 // coarse directory ignore like `demo/**` emits
 //
-//	demo/**/*.md -merge
-//	demo/**/*.markdown -merge
+//	demo/**/*.md merge=text
+//	demo/**/*.markdown merge=text
 //
-// rather than a bare `demo/** -merge`. The `ignore:` list scopes the
-// markdown linter (files: is *.md / *.markdown), so an ignore pattern
-// is only ever meant to affect markdown; a bare `-merge` line, by
-// contrast, is not extension-scoped and would disable git's 3-way
-// merge for every file in the tree — including source code that
+// rather than a bare `demo/** merge=text`. The `ignore:` list scopes
+// the markdown linter (files: is *.md / *.markdown), so an ignore
+// pattern is only ever meant to affect markdown; a bare exclude line,
+// by contrast, is not extension-scoped and would change git's merge
+// behaviour for every file in the tree — including source code that
 // nobody asked to grandfather (issue #750). scopeExcludeToMarkdown
 // guarantees every emitted exclude ends in a markdown extension.
 //
+// The exclude lines carry `merge=text` (git's built-in 3-way text
+// merge), not `-merge` (merge unset). Both take the mdsmith driver out
+// of the picture for the path, but `-merge` also forfeits git's text
+// merge and leaves the file binary-conflicting; the ignore-derived
+// paths are Markdown with no generated sections, so `merge=text` is
+// the correct, conflict-avoiding fallback (issue #755).
+//
 // Patterns that cannot be represented directly in .gitattributes
 // are dropped from the exclude set so MDS048's auto-fix never
 // produces a broken managed block:
@@ -217,12 +224,14 @@ func GlobsFromConfig(cfg *config.Config) (Globs, []string) {
 }
 
 // scopeExcludeToMarkdown rewrites one .mdsmith.yml ignore pattern into
-// the .gitattributes exclude patterns that turn off the mdsmith merge
-// driver for the Markdown files the pattern grandfathers — and only
-// those files (issue #750).
+// the .gitattributes exclude patterns that fall back to git's built-in
+// text merge (merge=text) for the Markdown files the pattern
+// grandfathers — and only those files (issue #750). The returned
+// patterns are the path field; RenderManagedBlock appends the
+// `merge=text` attribute.
 //
 // A pattern that already ends in one of exts targets a specific
-// Markdown extension, so its -merge line can only affect Markdown; it
+// Markdown extension, so its exclude line can only affect Markdown; it
 // is returned unchanged. Otherwise the pattern is treated as a path
 // scope and one exclude is emitted per extension, keyed on the final
 // path segment:
@@ -233,7 +242,7 @@ func GlobsFromConfig(cfg *config.Config) (Globs, []string) {
 //   - `dir`    -> `dir/**/*.md`, `dir/**/*.markdown` (name as a tree)
 //
 // Every branch appends a Markdown extension to the emitted pattern, so
-// the invariant "a derived -merge line never matches a non-Markdown
+// the invariant "a derived exclude line never matches a non-Markdown
 // file" holds for any input.
 func scopeExcludeToMarkdown(pattern string, exts []string) []string {
 	for _, ext := range exts {
@@ -664,20 +673,26 @@ func findManagedBlockLines(lines []string) (int, int) {
 // Globs describes the set of paths the mdsmith merge driver applies
 // to. Each Include pattern is written as `<pattern> merge=mdsmith`
 // and each Exclude pattern is written after them as `<pattern>
-// -merge`. .gitattributes uses last-match-wins, so an exclude line
-// after the include lines effectively removes the merge driver from
-// any path the include patterns matched.
+// merge=text`. .gitattributes uses last-match-wins, so an exclude line
+// after the include lines effectively removes the mdsmith merge driver
+// from any path the include patterns matched, falling back to git's
+// built-in 3-way text merge.
 //
 // Exclude patterns derived from .mdsmith.yml ignore entries are
-// markdown-scoped (see GlobsFromConfig): a `-merge` line only ever
-// matches a markdown file, so it disables the mdsmith driver for
+// markdown-scoped (see GlobsFromConfig): a `merge=text` line only ever
+// matches a markdown file, so it takes the mdsmith driver off
 // grandfathered markdown without touching git's default merge for
-// non-markdown files in the same tree (issue #750).
+// non-markdown files in the same tree (issue #750). Emitting
+// `merge=text` rather than `-merge` also keeps git's text merge for
+// those files instead of declaring them binary-conflicting (#755).
+//
+// ExtractGlobs still reads the legacy `-merge` exclude form so a
+// `.gitattributes` written by an older mdsmith round-trips unchanged.
 //
 // `.gitattributes` itself does not support negative patterns (`!*.md`
-// is a syntax error there). Order-sensitive override via -merge is the
-// supported way to express exclusions, which is why Globs keeps
-// Include and Exclude as separate ordered slices.
+// is a syntax error there). Order-sensitive override via a trailing
+// exclude line is the supported way to express exclusions, which is
+// why Globs keeps Include and Exclude as separate ordered slices.
 type Globs struct {
 	Include []string
 	Exclude []string
@@ -704,7 +719,17 @@ func RenderManagedBlock(globs Globs) string {
 		fmt.Fprintf(&b, "%s merge=mdsmith\n", p)
 	}
 	for _, p := range globs.Exclude {
-		fmt.Fprintf(&b, "%s -merge\n", p)
+		// Emit `merge=text`, not `-merge`. Both turn the mdsmith driver
+		// off for the path (last-match-wins over the include lines), but
+		// `-merge` also unsets git's built-in merge — declaring the file
+		// has no well-defined merge semantics, which is only correct for
+		// binaries and leaves these Markdown files binary-conflicting.
+		// `merge=text` selects git's built-in 3-way text merge instead.
+		// The excludes are ignore-derived Markdown paths (see
+		// GlobsFromConfig): they are never linted, so they carry no
+		// generated sections for the driver to reconcile, and the text
+		// merge is strictly safe (issue #755).
+		fmt.Fprintf(&b, "%s merge=text\n", p)
 	}
 	b.WriteString(gitattributesManagedBlockEnd)
 	b.WriteString("\n")
@@ -740,7 +765,14 @@ func ExtractGlobs(content string) (Globs, bool) {
 			switch attr {
 			case "merge=mdsmith":
 				globs.Include = append(globs.Include, pattern)
-			case "-merge":
+			case "merge=text", "-merge":
+				// `merge=text` is the current exclude form; `-merge` is
+				// the legacy form still found in blocks written by an
+				// older mdsmith (or the pinned CI baseline). Both mean
+				// "turn the mdsmith driver off for this path", so both
+				// map to an exclude — an unmigrated `-merge` block then
+				// extracts to the same glob set as a freshly rendered
+				// `merge=text` one and does not read as drift (#755).
 				globs.Exclude = append(globs.Exclude, pattern)
 			default:
 				continue

internal/githooks/githooks_test.go

@@ -1117,13 +1117,50 @@ func TestRenderManagedBlock_IncludeAndExclude(t *testing.T) {
 		Include: []string{"*.md", "*.markdown"},
 		Exclude: []string{"demo/**", "vendor/*.md"},
 	})
+	// Excludes are emitted as `merge=text`, not `-merge`: the ignore-
+	// derived paths are Markdown (well-defined text-merge semantics) and
+	// carry no generated sections, so falling back to git's built-in
+	// 3-way text merge avoids the binary-style conflicts `-merge` forces
+	// (issue #755). Last-match-wins still turns the mdsmith driver off.
 	expected := "# BEGIN mdsmith merge-driver\n" +
 		"*.md merge=mdsmith\n" +
 		"*.markdown merge=mdsmith\n" +
+		"demo/** merge=text\n" +
+		"vendor/*.md merge=text\n" +
+		"# END mdsmith merge-driver\n"
+	assert.Equal(t, expected, got)
+}
+
+func TestExtractGlobs_ParsesMergeTextExcludes(t *testing.T) {
+	// The current render form: excludes carry `merge=text`. ExtractGlobs
+	// must read them back as excludes so a freshly written block round-
+	// trips and drift detection does not report perpetual drift.
+	content := "# BEGIN mdsmith merge-driver\n" +
+		"*.md merge=mdsmith\n" +
+		"demo/** merge=text\n" +
+		"vendor/*.md merge=text\n" +
+		"# END mdsmith merge-driver\n"
+	got, ok := ExtractGlobs(content)
+	require.True(t, ok)
+	assert.Equal(t, []string{"*.md"}, got.Include)
+	assert.Equal(t, []string{"demo/**", "vendor/*.md"}, got.Exclude)
+}
+
+func TestExtractGlobs_ParsesLegacyDashMergeExcludes(t *testing.T) {
+	// Backward compatibility: a `.gitattributes` written by an older
+	// mdsmith (or by the pinned CI baseline) uses `-merge` for excludes.
+	// ExtractGlobs must still read those as excludes so an unmigrated
+	// committed block extracts to the same glob set as the merge=text
+	// form and does not read as drift.
+	content := "# BEGIN mdsmith merge-driver\n" +
+		"*.md merge=mdsmith\n" +
 		"demo/** -merge\n" +
 		"vendor/*.md -merge\n" +
 		"# END mdsmith merge-driver\n"
-	assert.Equal(t, expected, got)
+	got, ok := ExtractGlobs(content)
+	require.True(t, ok)
+	assert.Equal(t, []string{"*.md"}, got.Include)
+	assert.Equal(t, []string{"demo/**", "vendor/*.md"}, got.Exclude)
 }
 
 func TestRenderManagedBlock_EmptyGlobs(t *testing.T) {
@@ -1165,8 +1202,9 @@ func TestExtractGlobs_IgnoresCommentsAndBlankLinesInBlock(t *testing.T) {
 }
 
 func TestExtractGlobs_IgnoresUnknownAttributes(t *testing.T) {
-	// A line inside the managed block that is not a merge=mdsmith
-	// or -merge assignment must be ignored, not counted as a glob.
+	// A line inside the managed block that is not a merge=mdsmith,
+	// merge=text, or -merge assignment must be ignored, not counted
+	// as a glob.
 	content := "# BEGIN mdsmith merge-driver\n" +
 		"*.md merge=mdsmith\n" +
 		"*.txt text\n" +
@@ -1291,8 +1329,9 @@ func TestGlobsFromConfig_DropsUnrepresentablePatterns(t *testing.T) {
 
 func TestExtractGlobs_SkipsSingleFieldLines(t *testing.T) {
 	// A managed-block line with only a pattern (no attribute) is
-	// not a valid merge=mdsmith or -merge assignment; ExtractGlobs
-	// must skip it instead of treating the lone token as a glob.
+	// not a valid merge=mdsmith, merge=text, or -merge assignment;
+	// ExtractGlobs must skip it instead of treating the lone token
+	// as a glob.
 	content := "# BEGIN mdsmith merge-driver\n" +
 		"orphan-token\n" +
 		"*.md merge=mdsmith\n" +