add support for retaining multiline comments

[natefinch]

So I wrote out a beautiful long comment on my project's magefile package declaration, talking about the environment variables it supports etc... and mage mangled it.

I think this has been asked for before, and now it's here: retaining line returns in comments that get printed out as help text.

add

//mage:multiline

to your magefile or set MAGEFILE_MULTILINE=true in your environment, and mage will retain line returns from your comments in your help docs.

Note that this is a generation-time check, so if you use -compile, the compiled binary will be stuck with whatever choice was set on the machine that generated the binary. Since it can be part of the magefile itself, it didn't make sense to me to make it a runtime decision.

fixes #358

[Copilot]

Pull request overview

Adds an opt-in mechanism to preserve multiline doc comments (newlines/blank lines) when Mage renders package/target help text, addressing #358.

Changes:

• Add multiline-aware parsing of package/function doc strings, controlled by //mage:multiline and MAGEFILE_MULTILINE (plus a new CLI flag).
• Wire the new toggle through invocation/runtime config and into imported-package parsing.
• Update docs and add test coverage + new testdata magefiles for multiline behavior.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
parse/parse.go	Adds Multiline support to parsing and preserves newlines in descriptions/comments when enabled.
parse/parse_test.go	Updates tests for the new PrimaryPackage(..., multiline) signature.
mg/runtime.go	Introduces MAGEFILE_MULTILINE env var constant and accessor.
mage/main.go	Adds Invocation.Multiline, a new CLI flag, and passes multiline toggle into parsing.
mage/main_test.go	Adds tests validating multiline help/list output and tag override behavior.
mage/testdata/multiline/magefile.go	New testdata magefile used to validate env-var-controlled multiline output.
mage/testdata/multiline/tag/magefile.go	New testdata magefile used to validate //mage:multiline tag override behavior.
mage/magefile_tmpl.go	Updates mage -init template to include the multiline tag.
sh/testmain_test.go	Modifies package-level TestMain used by sh tests/helpers.
site/content/environment/_index.en.md	Documents MAGEFILE_MULTILINE and reorders environment variable docs.
site/content/magefiles/_index.en.md	Documents multiline help retention and shows //mage:multiline usage.
site/content/index.md	Updates homepage example to include //mage:multiline.

Comments suppressed due to low confidence (1)

mg/runtime.go:107

• Same issue as the MultilineEnv constant comment: Multiline() says it retains “CRLF line endings in comments for the generated main file”, but the behavior is about preserving newlines in help descriptions. Updating this comment will make the API clearer to callers.

// Multiline reports whether the user has requested to retain CRLF line endings
// in comments for the generated main file.
func Multiline() bool {
	b, _ := strconv.ParseBool(os.Getenv(MultilineEnv))
	return b
}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

TestMain no longer calls flag.Parse() and never calls os.Exit(m.Run()). Per testing package semantics, flags are not parsed before TestMain, and returning without running m.Run() will skip all tests in this package (and printArgs/helperCmd will never be set). Restore flag.Parse() and ensure the non-helper path exits with m.Run() so normal tests still execute.