summaryrefslogtreecommitdiffstats
path: root/Documentation/CodingGuidelines (follow)
Commit message (Collapse)AuthorAgeFilesLines
* Merge branch 'ps/build'Junio C Hamano2024-12-161-1/+1
|\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Build procedure update plus introduction of Meson based builds. * ps/build: (24 commits) Introduce support for the Meson build system Documentation: add comparison of build systems t: allow overriding build dir t: better support for out-of-tree builds Documentation: extract script to generate a list of mergetools Documentation: teach "cmd-list.perl" about out-of-tree builds Documentation: allow sourcing generated includes from separate dir Makefile: simplify building of templates Makefile: write absolute program path into bin-wrappers Makefile: allow "bin-wrappers/" directory to exist Makefile: refactor generators to be PWD-independent Makefile: extract script to generate gitweb.js Makefile: extract script to generate gitweb.cgi Makefile: extract script to massage Python scripts Makefile: extract script to massage Shell scripts Makefile: use "generate-perl.sh" to massage Perl library Makefile: extract script to massage Perl scripts Makefile: consistently use PERL_PATH Makefile: generate doc versions via GIT-VERSION-GEN Makefile: generate "git.rc" via GIT-VERSION-GEN ...
| * Makefile: allow "bin-wrappers/" directory to existPatrick Steinhardt2024-12-061-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | The "bin-wrappers/" directory gets created by our build system and is populated with one script for each of our binaries. There isn't anything inherently wrong with the current layout, but it is somewhat hard to adapt for out-of-tree build systems. Adapt the layout such that our "bin-wrappers/" directory always exists and contains our "wrap-for-bin.sh" script to make things a little bit easier for subsequent steps. Signed-off-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | Merge branch 'jc/doc-error-message-guidelines'Junio C Hamano2024-12-131-3/+17
|\ \ | |/ |/| | | | | | | | | Developer documentation update. * jc/doc-error-message-guidelines: CodingGuidelines: a handful of error message guidelines
| * CodingGuidelines: a handful of error message guidelinesJunio C Hamano2024-11-291-3/+17
| | | | | | | | | | | | | | | | | | | | | | | | It is more efficient to have something in the coding guidelines document to point at, when we want to review and comment on a new message in the codebase to make sure it "fits" in the set of existing messages. Let's write down established best practice we are aware of. Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | CodingGuidelines: discourage arbitrary suffixes in function namesKarthik Nayak2024-10-241-0/+14
| | | | | | | | | | | | | | | | | | | | We often name functions with arbitrary suffixes like `_1` as an extension of another existing function. This creates confusion and doesn't provide good clarity into the functions purpose. Let's document good function naming etiquette in our CodingGuidelines. Signed-off-by: Karthik Nayak <karthik.188@gmail.com> Signed-off-by: Taylor Blau <me@ttaylorr.com>
* | Merge branch 'ja/doc-synopsis-markup'Junio C Hamano2024-10-101-28/+30
|\ \ | |/ |/| | | | | | | | | | | | | | | | | The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. * ja/doc-synopsis-markup: doc: apply synopsis simplification on git-clone and git-init doc: update the guidelines to reflect the current formatting rules doc: introduce a synopsis typesetting
| * doc: update the guidelines to reflect the current formatting rulesJean-Noël Avila2024-09-241-28/+30
| | | | | | | | | | Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | CodingGuidelines: also mention MAYBE_UNUSEDJunio C Hamano2024-08-291-2/+3
| | | | | | | | | | | | | | | | | | | | | | | | A function that uses a parameter in one build may lose all uses of the parameter in another build, depending on the configuration. A workaround for such a case, MAYBE_UNUSED, should also be mentioned when we recommend the use of UNUSED to our developers. Keep the addition to the guideline short and document the criteria to choose between UNUSED and MAYBE_UNUSED near their definition. Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | CodingGuidelines: mention -Wunused-parameter and UNUSEDJeff King2024-08-281-0/+7
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Now that -Wunused-parameter is on by default for DEVELOPER=1 builds, people may trigger it, blocking their build. When it's a mistake for the parameter to exist, the path forward is obvious: remove it. But sometimes you need to suppress the warning, and the "UNUSED" mechanism for that is specific to our project, so people may not know about it. Let's put some advice in CodingGuidelines, including an example warning message. That should help people who grep for the warning text after seeing it from the compiler. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | Merge branch 'jc/coding-style-c-operator-with-spaces'Junio C Hamano2024-08-261-1/+10
|\ \ | | | | | | | | | | | | | | | | | | Write down whitespacing rules around C opeators. * jc/coding-style-c-operator-with-spaces: CodingGuidelines: spaces around C operators
| * | CodingGuidelines: spaces around C operatorsJunio C Hamano2024-08-201-1/+10
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | As we have operated with "write like how your surrounding code is written" for too long, after a huge code drop from another project, we'll end up being inconsistent before such an imported code is cleaned up. We have many uses of cast operator with a space before its operand, mostly in the reftable code. Spell the convention out before it spreads to other places. Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | | Merge branch 'jc/document-use-of-local'Junio C Hamano2024-08-141-2/+2
|\ \ \ | | | | | | | | | | | | | | | | | | | | | | | | Doc update. * jc/document-use-of-local: doc: note that AT&T ksh does not work with our test suite
| * | | doc: note that AT&T ksh does not work with our test suiteJunio C Hamano2024-07-151-2/+2
| | |/ | |/| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The scripted Porcelain commands do not allow use of "local" because it is not universally supported, but we use it liberally in our test scripts, which means some POSIX compliant shells (like "ksh93") can not be used to run our tests. Document the status quo, to help the next person who gets perplexed seeing our tests fail. Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | | Merge branch 'ps/doc-more-c-coding-guidelines'Junio C Hamano2024-08-081-1/+47
|\ \ \ | |_|/ |/| | | | | | | | | | | | | | | | | | | | | | | | | | Some project conventions have been added to CodingGuidelines. * ps/doc-more-c-coding-guidelines: Documentation: consistently use spaces inside initializers Documentation: document idiomatic function names Documentation: document naming schema for structs and their functions Documentation: clarify indentation style for C preprocessor directives clang-format: fix indentation width for preprocessor directives
| * | Documentation: consistently use spaces inside initializersPatrick Steinhardt2024-07-301-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Our coding guide is inconsistent with how it uses spaces inside of initializers (`struct foo bar = { something }`). While we mostly carry the space between open and closing braces and the initialized members, in one case we don't. Fix this one instance such that we consistently carry the space. This is also consistent with how clang-format formats such initializers. Signed-off-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>
| * | Documentation: document idiomatic function namesPatrick Steinhardt2024-07-301-0/+17
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | We semi-regularly have discussions around whether a function shall be named `S_release()`, `S_clear()` or `S_free()`. Indeed, it may not be obvious which of these is preferable as we never really defined what each of these variants means exactly. Carve out a space where we can add idiomatic names for common functions in our coding guidelines and define each of those functions. Like this, we can get to a shared understanding of their respective semantics and can easily point towards our style guide in future discussions such that our codebase becomes more consistent over time. Note that the intent is not to rename all functions which violate these semantics right away. Rather, the intent is to slowly converge towards a common style over time. Signed-off-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>
| * | Documentation: document naming schema for structs and their functionsPatrick Steinhardt2024-07-301-0/+19
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | We nowadays have a proper mishmash of struct-related functions that are called `<verb>_<struct>` (e.g. `clear_prio_queue()`) versus functions that are called `<struct>_<verb>` (e.g. `strbuf_clear()`). While the former style may be easier to tie into a spoken conversation, most of our communication happens in text anyway. Furthermore, prefixing functions with the name of the structure they operate on makes it way easier to group them together, see which functions are related, and will also help folks who are using code completion. Let's thus settle on one style, namely the one where functions start with the name of the structure they operate on. Signed-off-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>
| * | Documentation: clarify indentation style for C preprocessor directivesPatrick Steinhardt2024-07-301-0/+10
| |/ | | | | | | | | | | | | | | | | In the preceding commit, we have settled on using a single space per nesting level to indent preprocessor directives. Clarify our coding guidelines accordingly. Signed-off-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* / CodingGuidelines: document a shell that "fails" "VAR=VAL shell_func"Junio C Hamano2024-07-231-0/+27
|/ | | | | | | | | | | | | | | | | Over the years, we accumulated the community wisdom to avoid the common "one-short export" construct for shell functions, but seem to have lost on which exact platform it is known to fail. Now during an investigation on a breakage for a recent topic, we found one example of failing shell. Let's document that. This does *not* mean that we can freely start using the construct once Ubuntu 20.04 is retired. But it does mean that we cannot use the construct until Ubuntu 20.04 is fully retired from the machines that matter. Moreover, posix explicitly says that the behaviour for the construct is unspecified. Helped-by: Kyle Lippincott <spectral@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* Merge branch 'jc/local-extern-shell-rules'Junio C Hamano2024-04-161-0/+16
|\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | Document and apply workaround for a buggy version of dash that mishandles "local var=val" construct. * jc/local-extern-shell-rules: t1016: local VAR="VAL" fix t0610: local VAR="VAL" fix t: teach lint that RHS of 'local VAR=VAL' needs to be quoted t: local VAR="VAL" (quote ${magic-reference}) t: local VAR="VAL" (quote command substitution) t: local VAR="VAL" (quote positional parameters) CodingGuidelines: quote assigned value in 'local var=$val' CodingGuidelines: describe "export VAR=VAL" rule
| * CodingGuidelines: quote assigned value in 'local var=$val'Junio C Hamano2024-04-061-0/+12
| | | | | | | | | | | | | | | | | | | | | | | | Dash bug https://bugs.launchpad.net/ubuntu/+source/dash/+bug/139097 lets the shell erroneously perform field splitting on the expansion of a command substitution during declaration of a local or an extern variable. The explanation was stolen from ebee5580 (parallel-checkout: avoid dash local bug in tests, 2021-06-06). Signed-off-by: Junio C Hamano <gitster@pobox.com>
| * CodingGuidelines: describe "export VAR=VAL" ruleJunio C Hamano2024-04-061-0/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | https://lore.kernel.org/git/201307081121.22769.tboegi@web.de/ resulted in 9968ffff (test-lint: detect 'export FOO=bar', 2013-07-08) to add a rule to t/check-non-portable-shell.pl script to reject export VAR=VAL and suggest us to instead write it as two statements, i.e., VAR=VAL export VAR This however was not spelled out in the CodingGuidelines document. We may want to re-evaluate the rule since it is from ages ago, but for now, let's make the written rule and what the automation enforces consistent. Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | doc: rework CodingGuidelines with new formatting rulesJean-Noël Avila2024-03-291-68/+85
|/ | | | | | | | Literal and placeholder formatting is more heavily enforced, with some asciidoc magic. Basically, the markup is preserved everywhere. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* Merge branch 'jc/doc-compat-util'Junio C Hamano2024-03-051-6/+35
|\ | | | | | | | | | | | | | | Clarify wording in the CodingGuidelines that requires <git-compat-util.h> to be the first header file. * jc/doc-compat-util: doc: clarify the wording on <git-compat-util.h> requirement
| * doc: clarify the wording on <git-compat-util.h> requirementJunio C Hamano2024-02-271-6/+35
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The reason why we require the <git-compat-util.h> file to be the first header file to be included is because it insulates other header files and source files from platform differences, like which system header files must be included in what order, and what C preprocessor feature macros must be defined to trigger certain features we want out of the system. We tried to clarify the rule in the coding guidelines document, but the wording was a bit fuzzy that can lead to misinterpretations like you can include <xdiff/xinclude.h> only to avoid having to include <git-compat-util.h> even if you have nothing to do with the xdiff implementation, for example. "You do not have to include more than one of these" was also misleading and would have been puzzling if you _needed_ to depend on more than one of these approved headers (answer: you are allowed to include them all if you need the declarations in them for reasons other than that you want to avoid including compat-util yourself). Instead of using the phrase "approved headers", enumerate them as exceptions, each labeled with its intended audiences, to avoid such misinterpretations. The structure also makes it easier to add new exceptions, so add the description of "t/unit-tests/test-lib.h" being an exception only for the unit tests implementation as an example. Signed-off-by: Junio C Hamano <gitster@pobox.com> Acked-by: Kyle Lippincott <spectral@google.com> Acked-by: Elijah Newren <newren@gmail.com>
| * Merge branch 'js/contributor-docs-updates' into maint-2.43Junio C Hamano2024-02-091-2/+2
| |\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Doc update. * js/contributor-docs-updates: SubmittingPatches: hyphenate non-ASCII SubmittingPatches: clarify GitHub artifact format SubmittingPatches: clarify GitHub visual SubmittingPatches: provide tag naming advice SubmittingPatches: update extra tags list SubmittingPatches: discourage new trailers SubmittingPatches: drop ref to "What's in git.git" CodingGuidelines: write punctuation marks CodingGuidelines: move period inside parentheses
| * \ Merge branch 'js/update-urls-in-doc-and-comment' into maint-2.43Junio C Hamano2024-02-091-1/+1
| |\ \ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Stale URLs have been updated to their current counterparts (or archive.org) and HTTP links are replaced with working HTTPS links. * js/update-urls-in-doc-and-comment: doc: refer to internet archive doc: update links for andre-simon.de doc: switch links to https doc: update links to current pages
| * \ \ Merge branch 'tz/send-email-negatable-options' into maint-2.43Junio C Hamano2024-02-091-1/+1
| |\ \ \ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Newer versions of Getopt::Long started giving warnings against our (ab)use of it in "git send-email". Bump the minimum version requirement for Perl to 5.8.1 (from September 2002) to allow simplifying our implementation. * tz/send-email-negatable-options: send-email: avoid duplicate specification warnings perl: bump the required Perl version to 5.8.1 from 5.8.0
* | \ \ \ Merge branch 'ja/doc-placeholders-markup-rules' into HEADJunio C Hamano2024-03-011-0/+7
|\ \ \ \ \ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The way placeholders are to be marked-up in documentation have been specified; use "_<placeholder>_" to typeset the word inside a pair of <angle-brakets> emphasized. * ja/doc-placeholders-markup-rules: doc: clarify the format of placeholders
| * | | | | doc: clarify the format of placeholdersJean-Noël Avila2024-02-211-0/+7
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Add the new format rule when using placeholders in the description of commands and options. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | | | | | Merge branch 'js/contributor-docs-updates'Junio C Hamano2024-01-131-2/+2
|\ \ \ \ \ \ | | |_|_|_|/ | |/| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Doc update. * js/contributor-docs-updates: SubmittingPatches: hyphenate non-ASCII SubmittingPatches: clarify GitHub artifact format SubmittingPatches: clarify GitHub visual SubmittingPatches: provide tag naming advice SubmittingPatches: update extra tags list SubmittingPatches: discourage new trailers SubmittingPatches: drop ref to "What's in git.git" CodingGuidelines: write punctuation marks CodingGuidelines: move period inside parentheses
| * | | | | CodingGuidelines: write punctuation marksJosh Soref2023-12-281-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | - Match style in Release Notes Signed-off-by: Josh Soref <jsoref@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
| * | | | | CodingGuidelines: move period inside parenthesesJosh Soref2023-12-281-1/+1
| | |/ / / | |/| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The contents within parenthesis should be omittable without resulting in broken text. Eliding the parenthesis left a period to end a run without any content. Signed-off-by: Josh Soref <jsoref@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | | | | Merge branch 'js/update-urls-in-doc-and-comment'Junio C Hamano2023-12-181-1/+1
|\ \ \ \ \ | | |_|_|/ | |/| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Stale URLs have been updated to their current counterparts (or archive.org) and HTTP links are replaced with working HTTPS links. * js/update-urls-in-doc-and-comment: doc: refer to internet archive doc: update links for andre-simon.de doc: switch links to https doc: update links to current pages
| * | | | doc: update links to current pagesJosh Soref2023-11-261-1/+1
| | |/ / | |/| | | | | | | | | | | | | | | | | | | | | | It's somewhat traditional to respect sites' self-identification. Signed-off-by: Josh Soref <jsoref@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | | | Merge branch 'tz/send-email-negatable-options'Junio C Hamano2023-12-101-1/+1
|\ \ \ \ | |_|/ / |/| | / | | |/ | |/| | | | | | | | | | | | | | | | | | | Newer versions of Getopt::Long started giving warnings against our (ab)use of it in "git send-email". Bump the minimum version requirement for Perl to 5.8.1 (from September 2002) to allow simplifying our implementation. * tz/send-email-negatable-options: send-email: avoid duplicate specification warnings perl: bump the required Perl version to 5.8.1 from 5.8.0
| * | perl: bump the required Perl version to 5.8.1 from 5.8.0Todd Zullinger2023-11-161-1/+1
| |/ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The following commit will make use of a Getopt::Long feature which is only present in Perl >= 5.8.1. Document that as the minimum version we support. Many of our Perl scripts will continue to run with 5.8.0 but this change allows us to adjust them as needed without breaking any promises to our users. The Perl requirement was last changed in d48b284183 (perl: bump the required Perl version to 5.8 from 5.6.[21], 2010-09-24). At that time, 5.8.0 was 8 years old. It is now over 21 years old. Signed-off-by: Todd Zullinger <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | Merge branch 'jc/update-list-references-to-lore'Junio C Hamano2023-10-291-1/+1
|\ \ | | | | | | | | | | | | | | | | | | Doc update. * jc/update-list-references-to-lore: doc: update list archive reference to use lore.kernel.org
| * | doc: update list archive reference to use lore.kernel.orgJunio C Hamano2023-10-071-1/+1
| |/ | | | | | | | | | | | | | | | | | | | | | | | | | | 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 <gitster@pobox.com>
* | documentation: fix subject/verb agreementElijah Newren2023-10-091-1/+1
| | | | | | | | | | | | | | Diff best viewed with --color-diff. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | documentation: wording improvementsElijah Newren2023-10-091-2/+2
|/ | | | | | | Diff best viewed with --color-diff. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* Merge branch 'en/header-split-cache-h-part-3'Junio C Hamano2023-06-301-1/+1
|\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 ...
| * cache.h: remove this no-longer-used headerElijah Newren2023-06-211-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | Merge branch 'jt/doc-use-octal-with-printf'Junio C Hamano2023-06-231-0/+4
|\ \ | | | | | | | | | | | | | | | | | | | | | 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
| * | CodingGuidelines: use octal escapes, not hexJonathan Tan2023-06-141-0/+4
| |/ | | | | | | | | | | | | | | | | 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 <jonathantanmy@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* / docs: typofixesLinus Arver2023-06-121-1/+1
|/ | | | | | | | | | | 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 <linusa@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* treewide: ensure one of the appropriate headers is sourced firstElijah Newren2023-02-241-2/+6
| | | | | | | | | | | | | | | | | | | | | 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 <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* Merge branch 'ab/doc-synopsis-and-cmd-usage'Junio C Hamano2022-10-281-2/+12
|\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 "[<label>...]" 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 "_" ...
| * CodingGuidelines: update and clarify command-line conventionsÆvar Arnfjörð Bjarmason2022-10-131-2/+12
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 "<file>..." example (one or more) to "[<file>...]" (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 <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | Merge branch 'ab/coding-guidelines-c99'Junio C Hamano2022-10-201-10/+25
|\ \ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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
generated by cgit v1.2.3 (git 2.39.1) at 2025-01-30 16:08:04 +0100