git/Documentation/CodingGuidelines, branch v2.42.2

doc: update list archive reference to use lore.kernel.org

2023-10-06T23:46:59Z

No disrespect to other mailing list archives, but the local part of their URLs will become pretty much meaningless once the archives go out of service, and we learned the lesson hard way when $gmane stopped serving. Let's point into https://lore.kernel.org/ for an article that can be found there, because the local part of the URL has the Message-Id: that can be used to find the same message in other archives, even if lore goes down. Signed-off-by: Junio C Hamano

Merge branch 'en/header-split-cache-h-part-3'

2023-06-29T23:43:21Z

Header files cleanup. * en/header-split-cache-h-part-3: (28 commits) fsmonitor-ll.h: split this header out of fsmonitor.h hash-ll, hashmap: move oidhash() to hash-ll object-store-ll.h: split this header out of object-store.h khash: name the structs that khash declares merge-ll: rename from ll-merge git-compat-util.h: remove unneccessary include of wildmatch.h builtin.h: remove unneccessary includes list-objects-filter-options.h: remove unneccessary include diff.h: remove unnecessary include of oidset.h repository: remove unnecessary include of path.h log-tree: replace include of revision.h with simple forward declaration cache.h: remove this no-longer-used header read-cache*.h: move declarations for read-cache.c functions from cache.h repository.h: move declaration of the_index from cache.h merge.h: move declarations for merge.c from cache.h diff.h: move declaration for global in diff.c from cache.h preload-index.h: move declarations for preload-index.c from elsewhere sparse-index.h: move declarations for sparse-index.c from cache.h name-hash.h: move declarations for name-hash.c from cache.h run-command.h: move declarations for run-command.c from cache.h ...

Merge branch 'jt/doc-use-octal-with-printf'

2023-06-22T23:29:07Z

Suggest to refrain from using hex literals that are non-portable when writing printf(1) format strings. * jt/doc-use-octal-with-printf: CodingGuidelines: use octal escapes, not hex

cache.h: remove this no-longer-used header

2023-06-21T20:39:53Z

Since this header showed up in some places besides just #include statements, update/clean-up/remove those other places as well. Note that compat/fsmonitor/fsm-path-utils-darwin.c previously got away with violating the rule that all files must start with an include of git-compat-util.h (or a short-list of alternate headers that happen to include it first). This change exposed the violation and caused it to stop building correctly; fix it by having it include git-compat-util.h first, as per policy. Signed-off-by: Elijah Newren Signed-off-by: Junio C Hamano

CodingGuidelines: use octal escapes, not hex

2023-06-14T21:44:19Z

Extend the shell-scripting section of CodingGuidelines to suggest octal escape sequences (e.g. "\302\242") over hexadecimal (e.g. "\xc2\xa2") since the latter can be a source of portability problems. Signed-off-by: Jonathan Tan Signed-off-by: Junio C Hamano

docs: typofixes

2023-06-12T20:52:51Z

These were found with an automated CLI tool [1]. Only the "Documentation" subfolder (and not source code files) was considered because the docs are user-facing. [1]: https://crates.io/crates/typos-cli Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano

treewide: ensure one of the appropriate headers is sourced first

2023-02-24T01:25:28Z

We had several C files ignoring the rule to include one of the appropriate headers first; fix that. While at it, the rule in Documentation/CodingGuidelines about which header to include has also fallen out of sync, so update the wording to mention other allowed headers. Unfortunately, C files in reftable/ don't actually follow the previous or updated rule. If you follow the #include chain in its C files, reftable/system.h _tends_ to be first (i.e. record.c first includes record.h, which first includes basics.h, which first includees system.h), but not always (e.g. publicbasics.c includes another header first that does not include system.h). However, I'm going to punt on making actual changes to the C files in reftable/ since I do not want to risk bringing it out-of-sync with any version being used externally. Signed-off-by: Elijah Newren Signed-off-by: Junio C Hamano

Merge branch 'ab/doc-synopsis-and-cmd-usage'

2022-10-28T18:26:54Z

The short-help text shown by "git cmd -h" and the synopsis text shown at the beginning of "git help cmd" have been made more consistent. * ab/doc-synopsis-and-cmd-usage: (34 commits) tests: assert consistent whitespace in -h output tests: start asserting that *.txt SYNOPSIS matches -h output doc txt & -h consistency: make "worktree" consistent worktree: define subcommand -h in terms of command -h reflog doc: list real subcommands up-front doc txt & -h consistency: make "commit" consistent doc txt & -h consistency: make "diff-tree" consistent doc txt & -h consistency: use "[...]" for "zero or more" doc txt & -h consistency: make "annotate" consistent doc txt & -h consistency: make "stash" consistent doc txt & -h consistency: add missing options doc txt & -h consistency: use "git foo" form, not "git-foo" doc txt & -h consistency: make "bundle" consistent doc txt & -h consistency: make "read-tree" consistent doc txt & -h consistency: make "rerere" consistent doc txt & -h consistency: add missing options and labels doc txt & -h consistency: make output order consistent doc txt & -h consistency: add or fix optional "--" syntax doc txt & -h consistency: fix mismatching labels doc SYNOPSIS & -h: use "-" to separate words in labels, not "_" ...

Merge branch 'ab/coding-guidelines-c99'

2022-10-19T22:38:05Z

Update CodingGuidelines to clarify what features to use and avoid in C99. * ab/coding-guidelines-c99: CodingGuidelines: recommend against unportable C99 struct syntax CodingGuidelines: mention C99 features we can't use CodingGuidelines: allow declaring variables in for loops CodingGuidelines: mention dynamic C99 initializer elements CodingGuidelines: update for C99

CodingGuidelines: update and clarify command-line conventions

2022-10-13T16:32:54Z

Edit the section which explains how to create a good SYNOPSIS section for clarity and accuracy, it was mostly introduced in c455bd8950e (CodingGuidelines: Add a section on writing documentation, 2010-11-04): * Change "extra" example to "file", which now naturally follows from previous "..." example (one or more) to "[...]" (zero or more). * Explain how we prefer spacing around "[]()" tokens and "|" alternatives, this is not a new policy, but just codifies what's already the pattern in the most wide use in the documentation. Having a space around " | " for flags, but not for flag values is inconsistent, but this style guide codifies existing patterns. Grepping shows that we don't have any instance matching the second "Don't" example: git grep -E -h -o '=$[^)]+$' -- builtin Documentation/ Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano