git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH] docs: fix repository-layout when building with breaking changes

From
Junio C Hamano <gitster@pobox.com>
Date
Mar 3, 2025, 18:18 UTC
Message-ID
<xmqqbjuivuzm.fsf@gitster.g>
In-Reply-To
<pull.1871.git.1741018310447.gitgitgadget@gmail.com>
"Phillip Wood via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 6 quoted lines
>     I copied the name from the test prerequisite as I didn't want to have
>     different names for condition used in the tests and documentation. I do
>     have some reservations about the naming though as it means we end up
>     having to use ifdef::!without-breaking-changes[] or test_expect_success
>     !WITHOUT_BREAKING_CHANGES to document and test breaking changes which is
>     a double negative.

It was exactly the first thing that came to my mind when I saw the change to the Makefile in the patch. Unless our breaking changes are all removals, which is not likely to be the case in the longer term, "without-breaking-changes" would be an invitation for confusing double negatives.

Show 28 quoted lines
> +ifdef::without-breaking-changes[]
>  branches::
>  	A deprecated way to store shorthands to be used
>  	to specify a URL to 'git fetch', 'git pull' and 'git push'.
> @@ -164,6 +165,7 @@ branches::
>  	"$GIT_COMMON_DIR/branches" will be used instead.
>  +
>  Git will stop reading remotes from this directory in Git 3.0.
> +endif::without-breaking-changes[]
>  
>  hooks::
>  	Hooks are customization scripts used by various Git
> @@ -231,6 +233,7 @@ info/sparse-checkout::
>  	This file stores sparse checkout patterns.
>  	See also: linkgit:git-read-tree[1].
>  
> +ifdef::without-breaking-changes[]
>  remotes::
>  	Stores shorthands for URL and default refnames for use
>  	when interacting with remote repositories via 'git fetch',
> @@ -241,6 +244,7 @@ remotes::
>  	"$GIT_COMMON_DIR/remotes" will be used instead.
>  +
>  Git will stop reading remotes from this directory in Git 3.0.
> +endif::without-breaking-changes[]
>  
>  logs::
>  	Records of changes made to refs are stored in this directory.

The above parts of the documentation getting commented out all look sensible to exclude in a build that omits these older mechanisms. But can we do it with !with-breaking-changes instead?

Previous: Phillip Wood via GitGitGadgetNext: Patrick Steinhardt
Message 2 of 17 in “docs: fix repository-layout when building with breaking changes”
  1. docs: fix repository-layout when building with breaking changesPhillip Wood via GitGitGadget, Mar 3, 2025
  2. Junio C HamanoMar 3, 2025
  3. Patrick SteinhardtMar 4, 2025
  4. Phillip WoodMar 4, 2025
  5. Junio C HamanoMar 4, 2025
  6. docs: fix repository-layout when building with breaking changesPhillip Wood via GitGitGadget, Mar 5, 2025
  7. docs: fix check-docs with WITH_BREAKING_CHANGESJunio C Hamano, Mar 5, 2025
  8. Phillip WoodMar 7, 2025
  9. Phillip WoodMar 7, 2025
  10. Junio C HamanoMar 7, 2025
  11. Karthik NayakMar 7, 2025
  12. Phillip WoodMar 9, 2025
  13. Phillip WoodMar 9, 2025
  14. Patrick SteinhardtMar 10, 2025
  15. Patrick SteinhardtMar 11, 2025
  16. phillip.wood123@gmail.comMar 12, 2025
  17. Patrick SteinhardtMar 12, 2025

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.