From patchwork Sun Mar 24 22:18:56 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Jean-No=C3=ABl_Avila?= X-Patchwork-Id: 13600977 Received: from mail-wr1-f49.google.com (mail-wr1-f49.google.com [209.85.221.49]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 77A121CD10 for ; Sun, 24 Mar 2024 22:19:04 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.49 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711318746; cv=none; b=QHX/gC6h64w0y/FAjOD1UTn+zM7tKvfrmxU/edZIqtOzsLud/il5ScNk8j0l1CRyf5uEgULrPajB52XH89S626F739elvfF3D2pRUmHNYdp1Z92u7pQd7kbQq8LBMc6Mv7+BBYqJL5WDLsDfOaxF7MZxEvsCr1bSZSQtCOp6bSM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711318746; c=relaxed/simple; bh=NGN158k92hRt2Kl37HDc+kHDesQlbt82pY92wbroQmI=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=ej/yGnsimMp8CBZAAsEzTlXHkiDRtpl6X7jXsUg1h+rNAjxABloBwHtYGglDctm0rIQTU2yz7l0o3S+mkidJvwzLuA2/7Y2K9DQwILk5gG6V3d5TYCL9x+D3ke1dSgXP3sF647Xjfct0uexhKq3D3+gYuRz3Ty1zUk8FRGQbICo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=Y1fqh+zs; arc=none smtp.client-ip=209.85.221.49 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="Y1fqh+zs" Received: by mail-wr1-f49.google.com with SMTP id ffacd0b85a97d-33d90dfe73cso2014904f8f.0 for ; Sun, 24 Mar 2024 15:19:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1711318742; x=1711923542; darn=vger.kernel.org; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=k/PbPxtGJxH+6i9UCvkpYtZlUaH8lXExLAS4SZJsfFE=; b=Y1fqh+zs7G8NA/lAXc0hX57Fftq3Kk8nSYTI3ZCPGw9BVLpt4pS9wNgjhdnzpOxBVM fGLfecJdK/SRVrr2wJc/274NB8l6UnQs9kMBtjMe4ob4k0RhobQIcJX6GRtLXHQcT+fg DDOAkNiR8ui83zw/aIibxDRY/eNYY1RQQXvnyJpbiY/7oGTL2qpgY4f39R9Q8XGMly3u SArWyjI693fNCD/Jy1G6V77/B1TW7ZqNh6ntjOzxUbRD/pglSBn8NrwtcsfBQf/gXwpF oG0LMvqgXmW+5QLZdWRTBtZq/sluC2SiojaMNy98KaM11aEx0Hc0UclhuFvU/T/Yq7aj if4A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1711318742; x=1711923542; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=k/PbPxtGJxH+6i9UCvkpYtZlUaH8lXExLAS4SZJsfFE=; b=jCHDopJkUTOUavxJrQ62IswsKfB6Yab+qUFrrJIlcMiaY9lD9RAPPQhpPCUhHL4Xkv YkTRBdc4nlEKMlSqUDSmbPfX2S/wQ91LzHO9hI8o69CN7to2zHqQDyyJld/U9uaCeWve 0ZihjOd+MVs9/93XUTaygPL9v1cgReFxPhbj1zgUitkyeabYbMWVxyI5RRwUD8TuLVKX t5PfCVwQwMSROcns0NVCLtqutwnv83sh97+ozisLjuahqgMGspzSx5U8Oh+wYXrIiXcD hlKfRcrbYhCsrjjIR3ae/mXcUvEEpHj4ZYrV11rXo1yEi6jWjbDLFIz3w6DXWnliLg9g jsVQ== X-Gm-Message-State: AOJu0Yx4DzCck79HrF4wGm9TGm9onk42TIIpRbIbeac5ZEnvpTWtaNso jbYAtWFub1i6X83G1zUSZvt8tg/pwBNPXA/EjubtWJxvljLpgSnbj2BKwcV7 X-Google-Smtp-Source: AGHT+IGbXS57aFsUHJat3VEZnLUna5m1zAPdJIic2H9GlkZIUM/kIBCzGc4K8Rpb0vp/J1rSye5xIQ== X-Received: by 2002:a5d:664c:0:b0:33e:6faf:7740 with SMTP id f12-20020a5d664c000000b0033e6faf7740mr3685409wrw.13.1711318741816; Sun, 24 Mar 2024 15:19:01 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id du4-20020a0560000d4400b00341bdbf0b07sm5575302wrb.50.2024.03.24.15.19.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 24 Mar 2024 15:19:01 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Sun, 24 Mar 2024 22:18:56 +0000 Subject: [PATCH 1/4] doc: rework CodingGuidelines with new formatting rules Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Fcc: Sent To: git@vger.kernel.org Cc: =?utf-8?q?Jean-No=C3=ABl?= Avila , =?utf-8?q?Jean-No?= =?utf-8?q?=C3=ABl_Avila?= From: =?utf-8?q?Jean-No=C3=ABl_Avila?= From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= 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 --- Documentation/CodingGuidelines | 147 ++++++++++++++++++--------------- 1 file changed, 79 insertions(+), 68 deletions(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 32e69f798ee..b9e4c7cc19d 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -641,15 +641,15 @@ Writing Documentation: - Prefer succinctness and matter-of-factly describing functionality in the abstract. E.g. - --short:: Emit output in the short-format. + `--short`:: Emit output in the short-format. and avoid something like these overly verbose alternatives: - --short:: Use this to emit output in the short-format. - --short:: You can use this to get output in the short-format. - --short:: A user who prefers shorter output could.... - --short:: Should a person and/or program want shorter output, he - she/they/it can... + `--short`:: Use this to emit output in the short-format. + `--short`:: You can use this to get output in the short-format. + `--short`:: A user who prefers shorter output could.... + `--short`:: Should a person and/or program want shorter output, he + she/they/it can... This practice often eliminates the need to involve human actors in your description, but it is a good practice regardless of the @@ -659,12 +659,12 @@ Writing Documentation: addressing the hypothetical user, and possibly "we" when discussing how the program might react to the user. E.g. - You can use this option instead of --xyz, but we might remove + You can use this option instead of `--xyz`, but we might remove support for it in future versions. while keeping in mind that you can probably be less verbose, e.g. - Use this instead of --xyz. This option might be removed in future + Use this instead of `--xyz`. This option might be removed in future versions. - If you still need to refer to an example person that is @@ -682,68 +682,112 @@ Writing Documentation: The same general rule as for code applies -- imitate the existing conventions. - A few commented examples follow to provide reference when writing or - modifying command usage strings and synopsis sections in the manual - pages: - Placeholders are spelled in lowercase and enclosed in angle brackets: - - --sort= - --abbrev[=] +Markup: + + Literal parts (e.g. use of command-line options, command names, + branch names, URLs, pathnames (files and directories), configuration and + environment variables) must be typeset as verbatim (i.e. wrapped with + backticks): + `--pretty=oneline` + `git rev-list` + `remote.pushDefault` + `http://git.example.com` + `.git/config` + `GIT_DIR` + `HEAD` + + An environment variable must be prefixed with "$" only when referring to its + value and not when referring to the variable itself, in this case there is + nothing to add except the backticks: + `GIT_DIR` is specified + `$GIT_DIR/hooks/pre-receive` + + Word phrases enclosed in `backtick characters` are rendered literally + and will not be further expanded. The use of `backticks` to achieve the + previous rule means that literal examples should not use AsciiDoc + escapes. + Correct: + `--pretty=oneline` + Incorrect: + `\--pretty=oneline` + + Placeholders are spelled in lowercase and enclosed in + angle brackets surrounded by underscores: + __ + __ If a placeholder has multiple words, they are separated by dashes: - - --template= + __ + __ + + A placeholder is not enclosed in backticks, as it is not a literal. + + When needed, use a distinctive identifier for placeholders, usually + made of a qualification and a type: + __ + __ + + When literal and placeholders are mixed, each markup is applied for + each sub-entity. If they are stuck, a special markup, with an {empty} + entity is needed: + `--jobs` __ + `--sort=`{empty}____ + ____{empty}`/.git` + `remote.`{empty}____{empty}`.mirror` + +Synopsis Syntax - When a placeholder is cited in text paragraph, it is enclosed in angle - brackets to remind the reader the reference in the synopsis section. - For better visibility, the placeholder is typeset in italics: - The __ to be added. + Syntax grammar is formatted neither as literal nor as placeholder. + + A few commented examples follow to provide reference when writing or + modifying command usage strings and synopsis sections in the manual + pages: Possibility of multiple occurrences is indicated by three dots: - ... + __... (One or more of .) Optional parts are enclosed in square brackets: - [...] + [__...] (Zero or more of .) - --exec-path[=] + `--exec-path`[`=`{empty}____] (Option with an optional argument. Note that the "=" is inside the brackets.) - [...] + [__...] (Zero or more of . Note that the dots are inside, not outside the brackets.) Multiple alternatives are indicated with vertical bars: - [-q | --quiet] - [--utf8 | --no-utf8] + [`-q` | `--quiet`] + [`--utf8` | `--no-utf8`] Use spacing around "|" token(s), but not immediately after opening or before closing a [] or () pair: - Do: [-q | --quiet] - Don't: [-q|--quiet] + Do: [`-q` | `--quiet`] + Don't: [`-q`|`--quiet`] Don't use spacing around "|" tokens when they're used to separate the alternate arguments of an option: - Do: --track[=(direct|inherit)] - Don't: --track[=(direct | inherit)] + Do: `--track`[`=`(`direct`|`inherit`)]` + Don't: `--track`[`=`(`direct` | `inherit`)] Parentheses are used for grouping: - [( | )...] + [(__ | __)...] (Any number of either or . Parens are needed to make it clear that "..." pertains to both and .) - [(-p )...] + [(`-p` __)...] (Any number of option -p, each with one argument.) - git remote set-head (-a | -d | ) + `git remote set-head` __ (`-a` | `-d` | __) (One and only one of "-a", "-d" or "" _must_ (no square brackets) be provided.) And a somewhat more contrived example: - --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]] + `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]` Here "=" is outside the brackets, because "--diff-filter=" is a valid usage. "*" has its own pair of brackets, because it can (optionally) be specified only when one or more of the letters is @@ -754,39 +798,6 @@ Writing Documentation: the user would type into a shell and use 'Git' (uppercase first letter) when talking about the version control system and its properties. - A few commented examples follow to provide reference when writing or - modifying paragraphs or option/command explanations that contain options - or commands: - - Literal examples (e.g. use of command-line options, command names, - branch names, URLs, pathnames (files and directories), configuration and - environment variables) must be typeset in monospace (i.e. wrapped with - backticks): - `--pretty=oneline` - `git rev-list` - `remote.pushDefault` - `http://git.example.com` - `.git/config` - `GIT_DIR` - `HEAD` - - An environment variable must be prefixed with "$" only when referring to its - value and not when referring to the variable itself, in this case there is - nothing to add except the backticks: - `GIT_DIR` is specified - `$GIT_DIR/hooks/pre-receive` - - Word phrases enclosed in `backtick characters` are rendered literally - and will not be further expanded. The use of `backticks` to achieve the - previous rule means that literal examples should not use AsciiDoc - escapes. - Correct: - `--pretty=oneline` - Incorrect: - `\--pretty=oneline` - -A placeholder is not enclosed in backticks, as it is not a literal. - If some place in the documentation needs to typeset a command usage example with inline substitutions, it is fine to use +monospaced and inline substituted text+ instead of `monospaced literal text`, and with From patchwork Sun Mar 24 22:18:57 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Jean-No=C3=ABl_Avila?= X-Patchwork-Id: 13600978 Received: from mail-wm1-f46.google.com (mail-wm1-f46.google.com [209.85.128.46]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 899BE288DB for ; Sun, 24 Mar 2024 22:19:05 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.46 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711318747; cv=none; b=KVYgQg2KYV0eacaJWQHMVUqA5WSfQXZQHO2t9J3smh1ppyCrOMXUiMyEDnhO0gcExqJBWGWm0eI4ejDoxyGvBh/nb17PWVr07hFc14s6PmuwHZdNGRurFlNUfpFsIO1uHOi6BDHchtDHdwwkiRkoINkf8rVrWRkE8kLUchWHyoE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711318747; c=relaxed/simple; bh=UkF4hrfEO4rL64BOS8hylXJeSVeekcz63ErR7m0Eudc=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=Lb6U58CW33UzIwTjsXeSFO1/k37lOcxXbJ4TbSswVK5R/N/puI5wcnB4lbodddlFA33UAXIPt+rZRgkyusMQsfb1+f3zIf+3pltC+TR3TdsNXMCEA5S+7z7tus3hg0nKGsEwCY67KeIpkTBGJi15ia1GJqQjx1ygEOivVfozkW4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=a4ahUC24; arc=none smtp.client-ip=209.85.128.46 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="a4ahUC24" Received: by mail-wm1-f46.google.com with SMTP id 5b1f17b1804b1-41482aa8237so9844125e9.2 for ; Sun, 24 Mar 2024 15:19:05 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1711318743; x=1711923543; darn=vger.kernel.org; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=nG5PM73cqbTYJJbql1RWM9irH0dQDC8HRnVua/7OBmQ=; b=a4ahUC24bA1PL3jAkgYJv4mOrkYEPYUZgvBrr8E+Bu8h3dQ1ZCCbPjSndbXf2b1LZb IJsUfNVntG4KuS3WML6iyMx7PcfxvC+314xba8GNNdKu+zidb44juBv5BPe41tiNWaAT UVSePVxyPDK05Jf0msdSnJa1H8o/5lfiOiZzxd30s8eneGFuvaHKP56vwr0fgXB/2/Na h8ZH1KTEPBQLTbMXgWiIbZEFBkrCQIqp2APhFDYB9+nVjkLOzDSkkUB3pSZfppDndSee 2+KcJu4EbOY5pN69afB4GHbTjL0AHV7R88zBkS9nu5kh6uBAD0iWQ5XL6E1ND+HU+You XBdg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1711318743; x=1711923543; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=nG5PM73cqbTYJJbql1RWM9irH0dQDC8HRnVua/7OBmQ=; b=UcWOZmNBMB7JnbpXis559ZitkqmJniS+Xm8ASVz3uIPo+8rs0XfrktScM2M2kk9mvn NlpWyroXguQY8i4Yr039tQvvDnRjWZs9bxOqpHN6ZCXRV5SbdjBqMGMv6H41Swtlhxh/ QT5Eie4LZedhlRPk9zElOSX0Fp1vbZwuhbAiNeO4BuSh7/IwkjMsM0CjSY3Ar7K15T8g rdyljkEjg0zvVsRl69w8LZ6WYQWHply8dSadfL33JYnFlBMiIUl0zNWjNmsfG5XtKvwL c14KQBNFK50FjIsfi+4nlafRO4aph8sqmFupjV1nB8vRcJnqLLkxhtAITZ1Q6sOdUIk9 FXzw== X-Gm-Message-State: AOJu0YxhSs0S31cnIxRgupd052xWAmvkkV8KRwkRqtCFfm3r2DKRQ+P3 Sq1wISmfpu1o6bev7d41vN8aFKvap2R6d72Wn8+qTED9oYA9+S8fBGttaPOV X-Google-Smtp-Source: AGHT+IE+GcZZtNy4wdu6byWxxp6BjQ5Z5OM0MuVVcKUKlDnNQSdZnijo3wvKfCa2SCIYBKD8UyQlag== X-Received: by 2002:a05:600c:3146:b0:413:271d:8889 with SMTP id h6-20020a05600c314600b00413271d8889mr4722782wmo.11.1711318743534; Sun, 24 Mar 2024 15:19:03 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id u9-20020a05600c19c900b0041489d50c26sm743662wmq.27.2024.03.24.15.19.02 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 24 Mar 2024 15:19:02 -0700 (PDT) Message-Id: <202ed891463c134904b89a0d746d85bb62338d52.1711318739.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Sun, 24 Mar 2024 22:18:57 +0000 Subject: [PATCH 2/4] doc: allow literal and emphasis format in doc vs help tests Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Fcc: Sent To: git@vger.kernel.org Cc: =?utf-8?q?Jean-No=C3=ABl?= Avila , =?utf-8?q?Jean-No?= =?utf-8?q?=C3=ABl_Avila?= From: =?utf-8?q?Jean-No=C3=ABl_Avila?= From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= As the new formatting of literal and placeholders is introduced, the synopsis in the man pages can now hold additional markup with respect to the command help. Signed-off-by: Jean-Noël Avila --- t/t0450-txt-doc-vs-help.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh index cd3969e852b..e47599cbf26 100755 --- a/t/t0450-txt-doc-vs-help.sh +++ b/t/t0450-txt-doc-vs-help.sh @@ -59,7 +59,7 @@ txt_to_synopsis () { -e '/^\[verse\]$/,/^$/ { /^$/d; /^\[verse\]$/d; - + s/{empty}\|_\|`//g; s/{litdd}/--/g; s/'\''\(git[ a-z-]*\)'\''/\1/g; From patchwork Sun Mar 24 22:18:58 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Jean-No=C3=ABl_Avila?= X-Patchwork-Id: 13600979 Received: from mail-lj1-f171.google.com (mail-lj1-f171.google.com [209.85.208.171]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 611FD3F8D1 for ; Sun, 24 Mar 2024 22:19:07 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.208.171 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711318749; cv=none; b=P85S1KOguPcLbyb5o15m32ixqSWKdmZRy4TWBvo2cKXc29E++meeC1w9O50ItDcIfYMzVXvXvX7MZtZvDR+x2jrf32wAG0+a022+mWVAm5J0kUG8LV6BH/blBt/na85nhL9IQZlKDRyApewmwyw60neTK01kciNSVGpU5WgpG/o= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711318749; c=relaxed/simple; bh=uc2jIJdTSiwr2a2/9QM49rlFK8FvJ4vj8ILD2ub9/DQ=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=KVUyKNREfsxb4TGS9d8FD1LUotsBY6Sy63tz5834dN2yQfKZ3zCu7QLeCJHAGUgaV+7f7Y1fU/aTRF6U+IJq38veBf+th6gXLqMY+x/DgQtCAmaKG0k2QFJAFAvCN5Qk8Tw43U81/M/r7kYV2xEmqqR7Gwa6mI0ndIZ1+djei7c= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=a7dV8Sqe; arc=none smtp.client-ip=209.85.208.171 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="a7dV8Sqe" Received: by mail-lj1-f171.google.com with SMTP id 38308e7fff4ca-2d476d7972aso61896441fa.1 for ; Sun, 24 Mar 2024 15:19:07 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1711318745; x=1711923545; darn=vger.kernel.org; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=WpUV4VZwVVBFFsgAJl9tELMS4GewbewW/eKWWwgUmc0=; b=a7dV8SqePrB9d0erwOw3yPBw4/UHXY80q0buBpRU3K+lhHobNJtqqUjQZiDuIeIvXQ nAHhArlH8tmHgFqzIT+OGpbxsJtt9Egsjgd606gVnn37KpFX1TYdA7+1U9BteE4KRx/9 /Y091b94c91UVYkh7/LnrTeJlSMEBnZghAgg8vNKNPRf2uXWGZftgwSkaCbV57/ZbAQW meT80+TWep92yQovLR9zYao0EPhdNyEr5EF60sh9+Kt6OMKHaCP20BGqLOljI/XGS1Kc dfM16I41ZesvifI5InUeK8zze9T9fRublzx8Srcb4CUWqPp0PxxC8e4aPJYz+AFMF7AD hC7A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1711318745; x=1711923545; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=WpUV4VZwVVBFFsgAJl9tELMS4GewbewW/eKWWwgUmc0=; b=kgpdI7Ev9XDlKoIYdQgN/rrM58+uGMJaddLV0NJ7GDpCC9CJWchhbvGjYZRVIxPJcj klCKgg29UrzxeDNOPo/5MKIe4Q0M4TZ/ax1o4dsgntenLJXdo0Jmw4HhLcrpGfz5uR5Z nW7sX/aIvLOCdE792cufRjU45BPi3YoH1sLUZRaHnl+EGvbdlUEEhOeoXWDW5cqXlke2 MCEhalG8yDVCv4UHrlOdxgWR0QsGuzhoKl/e7nqqd0VHJ4WXrNppjTcqrELPjWNxYQo+ kuZEWyrEhjzdhE/awIizGAQBfR0w+dBaESdpwO/cymlv6w/2JFuYjO78TjlqL93Fc9bL Hokg== X-Gm-Message-State: AOJu0YyCILRRxdV8p8uftC8q4KMLiLJS4oT/X4mEKE4NSl155gJWw+Ug 2w865yg46Hdwhrkc/2PqNzzrTnkILyWpXVhGFUDokxaiNuv3Uj2BxaRePPy/ X-Google-Smtp-Source: AGHT+IHbGJJkpSWb3G07vi2WELmu71IxL0dbh+fDYby+jtV4/FAAzv/WPjLTmSM4afNScc43wzrRgg== X-Received: by 2002:a2e:8416:0:b0:2d6:93c9:1f87 with SMTP id z22-20020a2e8416000000b002d693c91f87mr3530942ljg.4.1711318744445; Sun, 24 Mar 2024 15:19:04 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id s12-20020a05600c384c00b0041488691eacsm2465649wmr.18.2024.03.24.15.19.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 24 Mar 2024 15:19:03 -0700 (PDT) Message-Id: <310f09fc81c75ef03eb00629db6302d1904585fe.1711318740.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Sun, 24 Mar 2024 22:18:58 +0000 Subject: [PATCH 3/4] doc: git-init: apply new documentation formatting guidelines Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Fcc: Sent To: git@vger.kernel.org Cc: =?utf-8?q?Jean-No=C3=ABl?= Avila , =?utf-8?q?Jean-No?= =?utf-8?q?=C3=ABl_Avila?= From: =?utf-8?q?Jean-No=C3=ABl_Avila?= From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= Signed-off-by: Jean-Noël Avila --- Documentation/config/init.txt | 4 +-- Documentation/git-init.txt | 46 +++++++++++++++++------------------ 2 files changed, 25 insertions(+), 25 deletions(-) diff --git a/Documentation/config/init.txt b/Documentation/config/init.txt index dd1d8332737..af03acdbcbb 100644 --- a/Documentation/config/init.txt +++ b/Documentation/config/init.txt @@ -3,8 +3,8 @@ ifndef::git-init[] :see-git-init: (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) endif::[] -init.templateDir:: +`init.templateDir`:: Specify the directory from which templates will be copied. {see-git-init} -init.defaultBranch:: +`init.defaultBranch`:: Allows overriding the default branch name e.g. when initializing a new repository. diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 2f864e11ed9..ac4c4a80e26 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -9,11 +9,11 @@ git-init - Create an empty Git repository or reinitialize an existing one SYNOPSIS -------- [verse] -'git init' [-q | --quiet] [--bare] [--template=] - [--separate-git-dir ] [--object-format=] - [--ref-format=] - [-b | --initial-branch=] - [--shared[=]] [] +`git init` [`-q` | `--quiet`] [`--bare`] [`--template=`{empty}____] + [`--separate-git-dir` __] [`--object-format=`{empty}____] + [`--ref-format=`{empty}____] + [`-b` __ | `--initial-branch=`{empty}____] + [`--shared`[`=`{empty}____]] [__] DESCRIPTION @@ -41,35 +41,35 @@ the repository to another place if `--separate-git-dir` is given). OPTIONS ------- --q:: ---quiet:: +`-q`:: +`--quiet`:: Only print error and warning messages; all other output will be suppressed. ---bare:: +`--bare`:: Create a bare repository. If `GIT_DIR` environment is not set, it is set to the current working directory. ---object-format=:: +`--object-format=`{empty}____:: Specify the given object __ (hash algorithm) for the repository. The valid values are `sha1` and (if enabled) `sha256`. `sha1` is the default. + include::object-format-disclaimer.txt[] ---ref-format=:: +`--ref-format=`{empty}____:: Specify the given ref storage __ for the repository. The valid values are: + include::ref-storage-format.txt[] ---template=:: +`--template=`{empty}____:: Specify the directory from which templates will be used. (See the "TEMPLATE DIRECTORY" section below.) ---separate-git-dir=:: +`--separate-git-dir=`{empty}____:: Instead of initializing the repository as a directory to either `$GIT_DIR` or `./.git/`, create a text file there containing the path to the actual @@ -78,15 +78,15 @@ repository. + If this is a reinitialization, the repository will be moved to the specified path. --b :: ---initial-branch=:: +`-b` __:: +`--initial-branch=`{empty}____:: Use __ for the initial branch in the newly created repository. If not specified, fall back to the default name (currently `master`, but this is subject to change in the future; the name can be customized via the `init.defaultBranch` configuration variable). ---shared[=(false|true|umask|group|all|world|everybody|)]:: +`--shared`[`=`(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|__)]:: Specify that the Git repository is to be shared amongst several users. This allows users belonging to the same group to push into that @@ -99,14 +99,14 @@ The option can have the following values, defaulting to `group` if no value is given: + -- -umask:: -false:: +`umask`:: +`false`:: Use permissions reported by umask(2). The default, when `--shared` is not specified. -group:: -true:: +`group`:: +`true`:: Make the repository group-writable, (and g+sx, since the git group may not be the primary group of all users). This is used to loosen the permissions of an @@ -115,13 +115,13 @@ permission bits (e.g. if umask is `0022`, using `group` will not remove read privileges from other (non-group) users). See `0xxx` for how to exactly specify the repository permissions. -all:: -world:: -everybody:: +`all`:: +`world`:: +`everybody`:: Same as `group`, but make the repository readable by all users. -:: +__:: __ is a 3-digit octal number prefixed with `0` and each file will have mode __. __ will override users'`umask(2)` From patchwork Sun Mar 24 22:18:59 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Jean-No=C3=ABl_Avila?= X-Patchwork-Id: 13600980 Received: from mail-wm1-f45.google.com (mail-wm1-f45.google.com [209.85.128.45]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id A5B573FB8B for ; Sun, 24 Mar 2024 22:19:08 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.45 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711318750; cv=none; b=pverTlPQ5o3njkajWYwEEDSeLVqSbNElvwFYvosJKbUJyP0/sdH5mDFe/3plPCyIUq+axzaplsDI3Yd1tQdDtUj6yYTy84QohcK3Z8OFygIiZdwAk0crvCYZXi65p1J6g5Ry5iXWCs4oTsuL8Y0OR5J+SFZxwACkYDLZX6tzdUo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711318750; c=relaxed/simple; bh=J5PS/X3TltXwi6QdB1XA2pR31RkPq3mNfuGVmC0vY5A=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=p6VZcSltqgag4N/upXoDYem0Cy3dSn6qK+dHCpl7jcD8M9R+S6mO7mMngrKvgV8KFVkYgHjNXxYyyrqpxSkXq0Jpq4q020Td9uPuKsqGIZDbosM4NRYRtulGEGxaNTD+UghuzX/fDc9hloqQPobr1egiHNb3bLMkPEGl6qyrh8Q= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=Sc6+XY8s; arc=none smtp.client-ip=209.85.128.45 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="Sc6+XY8s" Received: by mail-wm1-f45.google.com with SMTP id 5b1f17b1804b1-41485fe355bso4547625e9.1 for ; Sun, 24 Mar 2024 15:19:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1711318746; x=1711923546; darn=vger.kernel.org; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=75/8iULr/DRxQooUD8kC6xKdPlg68sjU5vMp4oHaDU0=; b=Sc6+XY8sV6sCjejAIUBvcViPtApmnKmy+uHPp9i5X8QIykv3AzD5IhShrgiMhpGLeh otH52f6dBh8azuHGfY5whi718i5ptSJTDyprhtjwBA/rQPQa0lcDkn8RRhFqhMa53PG+ GA+Ybgt3RGGGGB+rCOWuZlDQvUzf8FBNwaBRLQWhUKf59eIgS4vWVr2kxzF0T60KJZtP 1r4+ucXr+FxtwK1kcQAznKONSJ1plN6ovWrqQ7cdIQaS5q6jo1735Y4M+Fxu+WDA80LL fon34DPy2S/1B6rYFcK4dxQ2O7AQ/XqbfNIVhWfV7nWfUCOGLZEGuOsLb9wUBHa4z6uk BLeQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1711318746; x=1711923546; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=75/8iULr/DRxQooUD8kC6xKdPlg68sjU5vMp4oHaDU0=; b=VFQ/FS4+DVIOiGPWGsEl+uvyFJldgp4hsCEIww5iRpByB9xRtrS0x4z35MMbTw8Ojn ahS7KBnDIOh1NsQSFo4Y+Pn8TK9sJoAJadA65AUxueiwrzQ7JuTIR442qsJkh9jrIfWg GtApEbombFris51ZhuY4/y9BTA89eDtkW97CQ5PxQLIdPm1pl+5VopSlWj33VU1DznaZ X9Zf3bR6JJrM9HnBz8qyol9NLzI9hp6yrEgemForaXoN8/e/WmYnxNVFJp8Mo/wbCDhb /2YsdJE30m6IueslfhQ7eEhVsIc3vB8A6H9FGKrjUeu5VMvCNWUc/MmCKgJKubyjgoou OMSA== X-Gm-Message-State: AOJu0Yy4ewlb36Rn/0inlZ+RayCLCT2gzknc2L33HU3RX9MIu887cd2p Oa3iyq0+UjMEXZlaSEAj4lIFygK7xn4GRfMFFvMTX052qXJnZRzVFctCyyg4 X-Google-Smtp-Source: AGHT+IEqEzje8sfJOWmsU8112SNTWhDIIveL4j6u7IGuGc0azGftZI/GbLgiKVZkiVtx+KlXh04r0Q== X-Received: by 2002:a05:600c:1d08:b0:413:3941:d9ae with SMTP id l8-20020a05600c1d0800b004133941d9aemr3432498wms.31.1711318746226; Sun, 24 Mar 2024 15:19:06 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id m29-20020a05600c3b1d00b004147b5dd6f8sm6392917wms.9.2024.03.24.15.19.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 24 Mar 2024 15:19:04 -0700 (PDT) Message-Id: <5ae83d3f799e9ab84d5233f77cb91715415ae167.1711318740.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Sun, 24 Mar 2024 22:18:59 +0000 Subject: [PATCH 4/4] doc: git-clone: apply new documentation guidelines Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Fcc: Sent To: git@vger.kernel.org Cc: =?utf-8?q?Jean-No=C3=ABl?= Avila , =?utf-8?q?Jean-No?= =?utf-8?q?=C3=ABl_Avila?= From: =?utf-8?q?Jean-No=C3=ABl_Avila?= From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= Heavily apply literal and placeholder markup everywhere. Signed-off-by: Jean-Noël Avila --- Documentation/config/clone.txt | 23 +++++-- Documentation/git-clone.txt | 120 ++++++++++++++++----------------- Documentation/urls.txt | 22 +++--- 3 files changed, 88 insertions(+), 77 deletions(-) diff --git a/Documentation/config/clone.txt b/Documentation/config/clone.txt index d037b57f729..0e0a8a1ae4a 100644 --- a/Documentation/config/clone.txt +++ b/Documentation/config/clone.txt @@ -1,13 +1,22 @@ -clone.defaultRemoteName:: +`clone.defaultRemoteName`:: The name of the remote to create when cloning a repository. Defaults to - `origin`, and can be overridden by passing the `--origin` command-line + `origin`. +ifdef::git-clone[] + It can be overridden by passing the `--origin` command-line + option. +endif::[] +ifndef::git-clone[] + It can be overridden by passing the `--origin` command-line option to linkgit:git-clone[1]. +endif::[] +`clone.rejectShallow`:: + Reject cloning a repository if it is a shallow one. This can be overridden by + passing the `--reject-shallow` option on the command line. +ifndef::git-clone[] + See linkgit:git-clone[1] +endif::[] -clone.rejectShallow:: - Reject cloning a repository if it is a shallow one; this can be overridden by - passing the `--reject-shallow` option on the command line. See linkgit:git-clone[1] - -clone.filterSubmodules:: +`clone.filterSubmodules`:: If a partial clone filter is provided (see `--filter` in linkgit:git-rev-list[1]) and `--recurse-submodules` is used, also apply the filter to submodules. diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index f90977a8519..134b5278ca1 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -9,15 +9,15 @@ git-clone - Clone a repository into a new directory SYNOPSIS -------- [verse] -'git clone' [--template=] - [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] - [-o ] [-b ] [-u ] [--reference ] - [--dissociate] [--separate-git-dir ] - [--depth ] [--[no-]single-branch] [--no-tags] - [--recurse-submodules[=]] [--[no-]shallow-submodules] - [--[no-]remote-submodules] [--jobs ] [--sparse] [--[no-]reject-shallow] - [--filter= [--also-filter-submodules]] [--] - [] +`git clone` [`--template=`{empty}____] + [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`] + [`-o` __] [`-b` __] [`-u` __] [`--reference` __] + [`--dissociate`] [`--separate-git-dir` __] + [`--depth` __] [`--`[`no-`]`single-branch`] [`--no-tags`] + [`--recurse-submodules`[`=`{empty}____]] [`--`[`no-`]`shallow-submodules`] + [`--`[`no-`]`remote-submodules`] [`--jobs` __] [`--sparse`] [`--`[`no-`]`reject-shallow`] + [`--filter=`{empty}____] [`--also-filter-submodules`]] [`--`] __ + [__] DESCRIPTION ----------- @@ -31,7 +31,7 @@ currently active branch. After the clone, a plain `git fetch` without arguments will update all the remote-tracking branches, and a `git pull` without arguments will in addition merge the remote master branch into the -current master branch, if any (this is untrue when "--single-branch" +current master branch, if any (this is untrue when `--single-branch` is given; see below). This default configuration is achieved by creating references to @@ -42,12 +42,12 @@ configuration variables. OPTIONS ------- --l:: ---local:: +`-l`:: +`--local`:: When the repository to clone from is on a local machine, this flag bypasses the normal "Git aware" transport mechanism and clones the repository by making a copy of - HEAD and everything under objects and refs directories. + `HEAD` and everything under objects and refs directories. The files under `.git/objects/` directory are hardlinked to save space when possible. + @@ -67,14 +67,14 @@ links. source repository, similar to running `cp -r src dst` while modifying `src`. ---no-hardlinks:: +`--no-hardlinks`:: Force the cloning process from a repository on a local filesystem to copy the files under the `.git/objects` directory instead of using hardlinks. This may be desirable if you are trying to make a back-up of your repository. --s:: ---shared:: +`-s`:: +`--shared`:: When the repository to clone is on the local machine, instead of using hard links, automatically setup `.git/objects/info/alternates` to share the objects @@ -101,7 +101,7 @@ If you want to break the dependency of a repository cloned with `--shared` on its source repository, you can simply run `git repack -a` to copy all objects from the source repository into a pack in the cloned repository. ---reference[-if-able] :: +`--reference`[`-if-able`] __:: If the reference __ is on the local machine, automatically setup `.git/objects/info/alternates` to obtain objects from the reference __. Using @@ -115,7 +115,7 @@ objects from the source repository into a pack in the cloned repository. *NOTE*: see the NOTE for the `--shared` option, and also the `--dissociate` option. ---dissociate:: +`--dissociate`:: Borrow the objects from reference repositories specified with the `--reference` options only to reduce network transfer, and stop borrowing from them after a clone is made @@ -126,43 +126,43 @@ objects from the source repository into a pack in the cloned repository. same repository, and this option can be used to stop the borrowing. --q:: ---quiet:: +`-q`:: +`--quiet`:: Operate quietly. Progress is not reported to the standard error stream. --v:: ---verbose:: +`-v`:: +`--verbose`:: Run verbosely. Does not affect the reporting of progress status to the standard error stream. ---progress:: +`--progress`:: Progress status is reported on the standard error stream by default when it is attached to a terminal, unless `--quiet` is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. ---server-option=