summaryrefslogtreecommitdiff
path: root/Documentation/CodingGuidelines
Commit message (Collapse)AuthorAgeFilesLines
* treewide: ensure one of the appropriate headers is sourced firstElijah Newren2023-02-231-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-191-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
| * | CodingGuidelines: recommend against unportable C99 struct syntaxÆvar Arnfjörð Bjarmason2022-10-111-0/+5
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Per 33665d98e6b (reftable: make assignments portable to AIX xlc v12.01, 2022-03-28) forms like ".a.b = *c" can be replaced by using ".a = { .b = *c }" instead. We'll probably allow these sooner than later, but since the workaround is trivial let's note it among the C99 features we'd like to hold off on for now. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
| * | CodingGuidelines: mention C99 features we can't useÆvar Arnfjörð Bjarmason2022-10-101-0/+7
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The C99 section of the CodingGuidelines is a good overview of what we can use, but is sorely lacking in what we can't use. Something that comes up occasionally is the portability of %z. Per [1] we couldn't use it for the longest time due to MSVC not supporting it, but nowadays by requiring C99 we rely on the MSVC version that does, but we can't use it yet because a C library that MinGW uses doesn't support it. 1. https://lore.kernel.org/git/a67e0fd8-4a14-16c9-9b57-3430440ef93c@gmail.com/ Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
| * | CodingGuidelines: allow declaring variables in for loopsÆvar Arnfjörð Bjarmason2022-10-101-8/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Since 44ba10d6712 (revision: use C99 declaration of variable in for() loop, 2021-11-14) released with v2.35.0 we've had a variable declared with in a for loop. Since then we've had inadvertent follow-ups to that with at least cb2607759e2 (merge-ort: store more specific conflict information, 2022-06-18) released with v2.38.0. As November 2022 is within the window of this upcoming release, let's update the guideline to allow this. We can have the promised "revisit" discussion while this patch cooks, and drop it if it turns out that it is still premature, which is not expected to happen at this moment. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
| * | CodingGuidelines: mention dynamic C99 initializer elementsÆvar Arnfjörð Bjarmason2022-10-101-0/+5
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The first use of variables in initializer elements appears to have been 2b6854c863a (Cleanup variables in cat-file, 2007-04-21) released with v1.5.2. Some of those caused portability issues, and e.g. that "cat-file" use was changed in 66dbfd55e38 (Rewrite dynamic structure initializations to runtime assignment, 2010-05-14) which went out with v1.7.2. But curiously 66dbfd55e38 missed some of them, e.g. an archive.c use added in d5f53d6d6f2 (archive: complain about path specs that don't match anything, 2009-12-12), and another one in merge-index.c (later builtin/merge-index.c) in 0077138cd9d (Simplify some instances of run_command() by using run_command_v_opt()., 2009-06-08). As far as I can tell there's been no point since 2b6854c863a in 2007 where a compiler that didn't support this has been able to compile git. Presumably 66dbfd55e38 was an attempt to make headway with wider portability that ultimately wasn't completed. In any case, we are thoroughly reliant on this syntax at this point, so let's update the guidelines, see https://lore.kernel.org/git/xmqqy1tunjgp.fsf@gitster.g/ for the initial discussion. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
| * | CodingGuidelines: update for C99Ævar Arnfjörð Bjarmason2022-10-101-2/+6
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Since 7bc341e21b5 (git-compat-util: add a test balloon for C99 support, 2021-12-01) we've had a hard dependency on C99, but the prose in CodingGuidelines was written under the assumption that we were using C89 with a few C99 features. As the updated prose notes we'd still like to hold off on novel C99 features, but let's make it clear that we target that C version, and then enumerate new C99 features that are safe to use. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | | CodingGuidelines: allow grep -EĐoàn Trần Công Danh2022-09-211-2/+0
|/ / | | | | | | | | | | | | | | | | | | Despite forbidden by CodingGuidelines, our usage of 'grep -E' has been increased over the years, and noone has come and complained. Let's lift the restriction. Signed-off-by: Đoàn Trần Công Danh <congdanhqx@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | Documentation: fix various repeat word typosJacob Stopak2022-09-121-1/+1
|/ | | | | | | | | | | | | Inspired by 24966cd982 ("doc: fix repeated words", 08-09-2019), I ran "egrep -R "\<([a-zA-Z]+)\> \<\1\>" ./Documentation/*" to find current cases of repeated words such as "the the" that were quite clearly typos. There were many false positives reported, such as "really really" or valid uses of "that that" which I left alone. Signed-off-by: Jacob Stopak <jacob@initialcommit.io> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* Documentation/ToolsForGit.txt: Tools for developing GitCOGONI Guillaume2022-04-211-12/+4
| | | | | | | | | | | | | | | | | | This document gathers tips, scripts and configuration file to help people working on Git’s codebase use their favorite tools while following Git’s coding style. Move the part about Emacs configuration from CodingGuidelines to ToolsForGit.txt because it's the purpose of the new file centralize the information about tools. But, add a mention to Documentation/ToolsForGit.txt in CodingGuidelines because there is also information about the coding style in it. Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr> Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* Merge branch 'jc/coding-guidelines-decl-in-for-loop'Junio C Hamano2022-04-041-1/+4
|\ | | | | | | | | | | | | Coding Guidelines clarification. * jc/coding-guidelines-decl-in-for-loop: CodingGuidelines: give deadline for "for (int i = 0; ..."
| * CodingGuidelines: give deadline for "for (int i = 0; ..."Junio C Hamano2022-03-311-1/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | We raised the weather balloon to see if we can allow the construct in 44ba10d6 (revision: use C99 declaration of variable in for() loop, 2021-11-14), which was shipped as a part of Git v2.35. Document that fact in the coding guidelines, and more importantly, give ourselves a deadline to revisit and update. Let's declare that we will officially adopt the variable declaration in the initializaiton part of "for ()" statement this winter, unless we find that a platform we care about does not grok it. Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | C99: remove hardcoded-out !HAVE_VARIADIC_MACROS codeÆvar Arnfjörð Bjarmason2022-02-211-0/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Remove the "else" branches of the HAVE_VARIADIC_MACROS macro, which have been unconditionally omitted since 765dc168882 (git-compat-util: always enable variadic macros, 2021-01-28). Since were always omitted, anyone trying to use a compiler without variadic macro support to compile a git since version git v2.31.0 or later would have had a compilation error. 10 months across a few releases since then should have been enough time for anyone who cared to run into that and report the issue. In addition to that, for anyone unsetting HAVE_VARIADIC_MACROS we've been emitting extremely verbose warnings since at least ee4512ed481 (trace2: create new combined trace facility, 2019-02-22). That's because there is no such thing as a "region_enter_printf" or "region_leave_printf" format, so at least under GCC and Clang everything that includes trace.h (almost every file) emits a couple of warnings about that. There's a large benefit to being able to have a hard dependency rely on variadic macros, the code surrounding usage.c is hard to maintain if we need to write two implementations of everything, and by relying on "__FILE__" and "__LINE__" along with "__VA_ARGS__" we can in the future make error(), die() etc. log where they were called from. We've also recently merged d67fc4bf0ba (Merge branch 'bc/require-c99', 2021-12-10) which further cements our hard dependency on C99. So let's delete the fallback code, and update our CodingGuidelines to note that we depend on this. The added bullet-point starts with lower-case for consistency with other bullet-points in that section. The diff in "trace.h" is relatively hard to read, since we need to retain the existing API docs, which were comments on the code used if HAVE_VARIADIC_MACROS was not defined. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | CodingGuidelines: hint why we value clearly written log messagesJunio C Hamano2022-01-271-0/+7
|/ | | | Signed-off-by: Junio C Hamano <gitster@pobox.com>
* CodingGuidelines: document which output goes to stdout vs. stderrEric Sunshine2021-12-041-0/+27
| | | | | | | | | | | | | | | It has long been practice on this project for a command to emit its primary output to stdout so that it can be captured to a file or sent down a pipe, and to emit "chatty" messages (such as those reporting progress) to stderr so that they don't interfere with the primary output. However, this practice is not necessarily universal; another common practice is to send only error messages to stderr, and all other messages to stdout. Therefore, help newcomers out by documenting how stdout and stderr are used on this project. Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Acked-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* Merge branch 'ds/gender-neutral-doc-guidelines'Junio C Hamano2021-07-281-0/+45
|\ | | | | | | | | | | | | A guideline for gender neutral documentation has been added. * ds/gender-neutral-doc-guidelines: CodingGuidelines: recommend gender-neutral description
| * CodingGuidelines: recommend gender-neutral descriptionJunio C Hamano2021-07-161-0/+45
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Technical writing seeks to convey information with minimal friction. One way that a reader can experience friction is if they encounter a description of "a user" that is later simplified using a gendered pronoun. If the reader does not consider that pronoun to apply to them, then they can experience cognitive dissonance that removes focus from the information. Give some basic tips to guide us avoid unnecessary uses of gendered description. Using a gendered pronoun is appropriate when referring to a specific person. There are acceptable existing uses of gendered pronouns within the Git codebase, such as: * References to real people (e.g. Linus Torvalds, "the Git maintainer"). Do not misgender real people. If there is any doubt to the gender of a person, then avoid using pronouns. * References to fictional people with clear genders (e.g. Alice and Bob). * Sample text used in test cases (e.g t3702, t6432). * The official text of the GPL license contains uses of "he or she", but using singular "they" (or modifying the text in some other way) is not within the scope of the Git project. * Literal email messages in Documentation/howto/ should not be edited for grammatical concerns such as this, unless we update the entire document to fit the standard documentation format. If such an effort is taken on, then the authorship would change and no longer refer to the exact mail message. * External projects consumed in contrib/ should not deviate solely for style reasons. Recommended edits should be contributed to those projects directly. Other cases within the Git project were cleaned up by the previous changes. Co-authored-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Derrick Stolee <dstolee@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | Merge branch 'jc/test-allows-local'Junio C Hamano2021-05-111-0/+5
|\ \ | | | | | | | | | | | | | | | | | | Document that our test can use "local" keyword. * jc/test-allows-local: CodingGuidelines: explicitly allow "local" for test scripts
| * | CodingGuidelines: explicitly allow "local" for test scriptsJunio C Hamano2021-05-031-0/+5
| |/ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 01d3a526 (t0000: check whether the shell supports the "local" keyword, 2017-10-26) raised a test balloon to see if those who build and test Git use a platform with a shell that lacks support for the "local" keyword. After two years, 7f0b5908 (t0000: reword comments for "local" test, 2019-08-08) documented that "local" keyword, even though is outside POSIX, is allowed in our test scripts. Let's write it in the CodingGuidelines, too. It might be tempting to allow it in scripted Porcelains (we have avoided getting them contaminiated by "local" so far), but they are on their way out and getting rewritten in C. Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | doc: clarify "do not capitalize the first word" ruleJunio C Hamano2021-04-141-1/+6
|/ | | | | | | | | | | | | | | | | | The same "do not capitalize the first word" rule is applied to both our patch titles and error messages, but the existing description was fuzzy in two aspects. * For error messages, it was not said that this was only about the first word that begins the sentence. * For both, it was not clear when a capital letter there was not an error. We avoid capitalizing the first word when the only reason you would capitalize it is because it happens to be the first word in the sentence. If a proper noun, which is usually spelled in capital letters, happens to come at the beginning of the sentence, it should be kept in capital letters. Signed-off-by: Junio C Hamano <gitster@pobox.com>
* Merge branch 'dl/python-2.7-is-the-floor-version'Junio C Hamano2020-06-171-6/+1
|\ | | | | | | | | | | | | Document that we do not support Python 2.6 or older. * dl/python-2.7-is-the-floor-version: CodingGuidelines: specify Python 2.7 is the oldest version
| * CodingGuidelines: specify Python 2.7 is the oldest versionDenton Liu2020-06-081-6/+1
| | | | | | | | | | | | | | | | | | | | In 0b4396f068 (git-p4: make python2.7 the oldest supported version, 2019-12-13), git-p4 was updated to only support 2.7 and newer. Since Python 2.6 is pretty much ancient history, update CodingGuidelines to show that 2.7 is the oldest version supported. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | Merge branch 'jc/codingstyle-compare-with-null'Junio C Hamano2020-05-141-0/+12
|\ \ | | | | | | | | | | | | | | | | | | Doc update. * jc/codingstyle-compare-with-null: CodingGuidelines: do not ==/!= compare with 0 or '\0' or NULL
| * | CodingGuidelines: do not ==/!= compare with 0 or '\0' or NULLJunio C Hamano2020-05-081-0/+12
| |/ | | | | | | | | | | Signed-off-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | Merge branch 'jk/arith-expansion-coding-guidelines'Junio C Hamano2020-05-081-4/+0
|\ \ | | | | | | | | | | | | | | | | | | | | | | | | | | | The coding guideline for shell scripts instructed to refer to a variable with dollar-sign inside arithmetic expansion to work around a bug in old versions of dash, which is a thing of the past. Now we are not forbidden from writing $((var+1)). * jk/arith-expansion-coding-guidelines: CodingGuidelines: drop arithmetic expansion advice to use "$x"
| * | CodingGuidelines: drop arithmetic expansion advice to use "$x"Jeff King2020-05-041-4/+0
| |/ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The advice to use "$x" rather than "x" in arithmetric expansion was working around a dash bug fixed in 0.5.4. Even Debian oldstable has 0.5.8 these days. And in the meantime, we've added almost two dozen instances of the "x" form which you can find with: git grep '$(([a-z]' and nobody seems to have complained. Let's declare this workaround obsolete and simplify our style guide. Helped-by: Danh Doan <congdanhqx@gmail.com> Signed-off-by: Jeff King <peff@peff.net> Reviewed-by: Carlo Marcelo Arenas Belón <carenas@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | Merge branch 'jc/allow-strlen-substitution-in-shell-scripts'Junio C Hamano2020-04-221-2/+0
|\ \ | |/ |/| | | | | | | | | Coding guideline update. * jc/allow-strlen-substitution-in-shell-scripts: CodingGuidelines: allow ${#posix} == strlen($posix)
| * CodingGuidelines: allow ${#posix} == strlen($posix)Junio C Hamano2020-03-291-2/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | | | The construct has been in POSIX for the past 10+ years, and we have used in t9xxx (subversion) series of the tests, so we know it is at portable across systems that people have run those tests, which is almost everything we'd care about. Let's loosen the rule; luckily, the check-non-portable-shell script does not have any rule to find its use, so the only change needed is a removal of one paragraph from the documentation. Helped-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | Documentation: fix a bunch of typos, both old and newElijah Newren2019-11-071-2/+2
|/ | | | | | Reported-by: Jens Schleusener <Jens.Schleusener@fossies.org> Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* Merge branch 'jc/post-c89-rules-doc'Junio C Hamano2019-07-251-3/+23
|\ | | | | | | | | | | | | | | | | We have been trying out a few language features outside c89; the coding guidelines document did not talk about them and instead had a blanket ban against them. * jc/post-c89-rules-doc: CodingGuidelines: spell out post-C89 rules
| * CodingGuidelines: spell out post-C89 rulesJunio C Hamano2019-07-181-3/+23
| | | | | | | | | | | | | | | | | | | | | | | | | | Even though we have been sticking to C89, there are a few handy features we borrow from more recent C language in our codebase after trying them in weather balloons and saw that nobody screamed. Spell them out. While at it, extend the existing variable declaration rule a bit to read better with the newly spelled out rule for the for loop. Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | Merge branch 'es/git-debugger-doc'Junio C Hamano2019-06-171-0/+6
|\ \ | |/ |/| | | | | | | | | Doc update. * es/git-debugger-doc: doc: hint about GIT_DEBUGGER in CodingGuidelines
| * doc: hint about GIT_DEBUGGER in CodingGuidelinesEmily Shaffer2019-05-281-0/+6
| | | | | | | | | | | | | | | | | | | | We check for a handy environment variable GIT_DEBUGGER when running via bin-wrappers/, but this feature is undocumented. Add a hint to how to use it into the CodingGuidelines (which is where other useful environment settings like DEVELOPER are documented). Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | doc/CodingGuidelines: URLs and paths as monospaceCorentin BOMPARD2019-03-131-2/+5
|/ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The current documentation uses both quotes (italics) and backquotes (monospace) to render URLs and pathnames, which is inconsistent. Document a best practice in CodingGuidelines to help reduce inconsistencies in the future. We set the best practice to using backquotes, since: * It is already an established practice. For exemple: $ git grep "'[^']/*[^']'" | wc -l 206 $ git grep '`[^`]/*[^`]`' | wc -l 690 There are false positives on both sides, but after a cursory look at the output of both, it doesn't seem the false positive rate is really higher in the second case. At least, this shows that the existing documentation uses inconsistent formatting, and that it would be good to do something about it. * It may be debatable whether path names need to be typed in monospace but having them in italics is really unusual. Signed-off-by: Corentin BOMPARD <corentin.bompard@etu.univ-lyon1.fr> Signed-off-by: Nathan BERBEZIER <nathan.berbezier@etu.univ-lyon1.fr> Signed-off-by: Pablo CHABANNE <pablo.chabanne@etu.univ-lyon1.fr> Signed-off-by: Matthieu MOY <matthieu.moy@univ-lyon1.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* Merge branch 'jc/how-to-document-api'Junio C Hamano2018-10-191-1/+4
|\ | | | | | | | | | | | | Doc update. * jc/how-to-document-api: CodingGuidelines: document the API in *.h files
| * CodingGuidelines: document the API in *.h filesJunio C Hamano2018-09-291-1/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | It makes it harder to let the API description and the reality drift apart if the doc is kept close to the implementation or the header of the API. We have been slowly migrating API docs out of the Documentation/technical/api-* to *.h files, and the development community generally considers that how inline docs in strbuf.h is done the best current practice. We recommend documenting in the header over documenting near the implementation to encourage people to write the docs that are readable without peeking at the implemention. Helped-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | Documentation: add shell guidelinesMatthew DeVore2018-10-071-0/+18
|/ | | | | | | | | | | | | | | | Add the following guideline to Documentation/CodingGuidelines: Break overlong lines after "&&", "||", and "|", not before them; that way the command can continue to subsequent lines without backslash at the end. And the following to t/README (since it is specific to writing tests): Pipes and $(git ...) should be avoided when they swallow exit codes of Git processes Signed-off-by: Matthew DeVore <matvore@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* CodingGuidelines: mention "static" and "extern"jk/doc-do-not-write-externJeff King2018-02-081-0/+5
| | | | | | | | | | | | | | | | | | | | | It perhaps goes without saying that file-local stuff should be marked static, but it does not hurt to remind people. Less obvious is that we are settling on "do not include extern in function declarations". It is already the default unless the function was previously declared static (but if you are following a static declaration with an unmarked one, you should think about why you are declaring the thing twice). And so it just becomes an extra noise-word in our header files. We used to give the opposite advice, so there are quite a few "extern" markers in early Git code. But this at least makes a concrete suggestion that we can follow going forward. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* Merge branch 'ab/c-translators-comment-style'Junio C Hamano2017-06-041-5/+5
|\ | | | | | | | | | | | | | | | | Update the C style recommendation for notes for translators, as recent versions of gettext tools can work with our style of multi-line comments. * ab/c-translators-comment-style: C style: use standard style for "TRANSLATORS" comments
| * C style: use standard style for "TRANSLATORS" commentsab/c-translators-comment-styleÆvar Arnfjörð Bjarmason2017-05-311-5/+5
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Change all the "TRANSLATORS: [...]" comments in the C code to use the regular Git coding style, and amend the style guide so that the example there uses that style. This custom style was necessary back in 2010 when the gettext support was initially added, and was subsequently documented in commit cbcfd4e3ea ("i18n: mention "TRANSLATORS:" marker in Documentation/CodingGuidelines", 2014-04-18). GNU xgettext hasn't had the parsing limitation that necessitated this exception for almost 3 years. Since its 0.19 release on 2014-06-02 it's been able to recognize TRANSLATOR comments in the standard Git comment syntax[1]. Usually we'd like to keep compatibility with software that's that young, but in this case literally the only person who needs to be using a gettext newer than 3 years old is Jiang Xin (the only person who runs & commits "make pot" results), so I think in this case we can make an exception. This xgettext parsing feature was added after a thread on the Git mailing list[2] which continued on the bug-gettext[3] list, but we never subsequently changed our style & styleguide, do so. There are already longstanding changes in git that use the standard comment style & have their TRANSLATORS comments extracted properly without getting the literal "*"'s mixed up in the text, as would happen before xgettext 0.19. Commit 7ff2683253 ("builtin-am: implement -i/--interactive", 2015-08-04) added one such comment, which in commit df0617bfa7 ("l10n: git.pot: v2.6.0 round 1 (123 new, 41 removed)", 2015-09-05) got picked up in the po/git.pot file with the right format, showing that Jiang already runs a modern xgettext. The xgettext parser does not handle the sort of non-standard comment style that I'm amending here in sequencer.c, but that isn't standard Git comment syntax anyway. With this change to sequencer.c & "make pot" the comment in the pot file is now correct: #. TRANSLATORS: %s will be "revert", "cherry-pick" or -#. * "rebase -i". +#. "rebase -i". 1. http://git.savannah.gnu.org/cgit/gettext.git/commit/?id=10af7fe6bd 2. <2ce9ec406501d112e032c8208417f8100bed04c6.1397712142.git.worldhello.net@gmail.com> (https://public-inbox.org/git/2ce9ec406501d112e032c8208417f8100bed04c6.1397712142.git.worldhello.net@gmail.com/) 3. https://lists.gnu.org/archive/html/bug-gettext/2014-04/msg00016.html Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Acked-by: Jiang Xin <worldhello.net@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | doc: replace a couple of broken gmane linksÆvar Arnfjörð Bjarmason2017-05-081-1/+1
|/ | | | | | | | | | | | | | | | Replace a couple of broken links to gmane with links to other archives. See commit 54471fdcc3 ("README: replace gmane link with public-inbox", 2016-12-15) for prior art. With this change there's still 4 references left in the code: $ git grep -E '(article|thread)\.gmane.org' -- |grep -v RelNotes|wc -l 4 I couldn't find alternative links for those. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* CodingGuidelines: clarify multi-line brace stylejk/coding-guidelines-updateJeff King2017-01-171-5/+32
| | | | | | | | | | There are some "gray areas" around when to omit braces from a conditional or loop body. Since that seems to have resulted in some arguments, let's be a little more clear about our preferred style. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* CodingGuidelines: formatting HEAD in documentationMatthieu Moy2016-06-281-2/+3
| | | | | | | | | | | | | | The current practice is: git/Documentation$ git grep "'HEAD'" | wc -l 24 git/Documentation$ git grep "\`HEAD\`" | wc -l 66 Let's adopt the majority as a guideline. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* doc: clearer rule about formatting literalsTom Russello2016-06-081-3/+10
| | | | | | | | | | | Make the guideline text that we want for our documentation clearer. Signed-off-by: Tom Russello <tom.russello@grenoble-inp.org> Signed-off-by: Erwan Mathoniere <erwan.mathoniere@grenoble-inp.org> Signed-off-by: Samuel Groot <samuel.groot@grenoble-inp.org> Signed-off-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr> Reviewed-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* add DEVELOPER makefile knob to check for acknowledged warningsls/makefile-cflags-developer-tweakLars Schneider2016-02-251-0/+5
| | | | | | | | | | | | We assume Git developers have a reasonably modern compiler and recommend them to enable the DEVELOPER makefile knob to ensure their patches are clear of all compiler warnings the Git core project cares about. Enable the DEVELOPER makefile knob in the Travis-CI build. Suggested-by: Jeff King <peff@peff.net> Signed-off-by: Lars Schneider <larsxschneider@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* Merge branch 'jg/cguide-we-cannot-count'Junio C Hamano2015-04-141-1/+1
|\ | | | | | | | | * jg/cguide-we-cannot-count: CodingGuidelines: update 'rough' rule count
| * CodingGuidelines: update 'rough' rule countjg/cguide-we-cannot-countJulian Gindi2015-04-141-1/+1
| | | | | | | | | | | | | | | | | | | | Changed inaccurate count of "rough rules" from three to the more generic 'a few'. Signed-off-by: Julian Gindi <juliangindi@gmail.com> Reviewed-by: Eric Sunshine <sunshine@sunshineco.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
* | *config.txt: stick to camelCase naming conventionnd/config-doc-camelCaseNguyễn Thái Ngọc Duy2015-03-131-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This should improve readability. Compare "thislongname" and "thisLongName". The following keys are left in unchanged. We can decide what to do with them later. - am.keepcr - core.autocrlf .safecrlf .trustctime - diff.dirstat .noprefix - gitcvs.usecrlfattr - gui.blamehistoryctx .trustmtime - pull.twohead - receive.autogc - sendemail.signedoffbycc .smtpsslcertpath .suppresscc Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
View Lorry Controller Status