From patchwork Fri Mar 29 11:19:37 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: 13610557 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 B0E343A1D8 for ; Fri, 29 Mar 2024 11:19:47 +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=1711711189; cv=none; b=LzISLS0RyODt9OHfh0cBTq/cXO+omcUfiIBPLaXpFixaFhnrJ4U7Rtecx2Gytg1mImEp3ffBQ3SldGlvOCIr29XlR6dUMRx+bmsZ+CxkLIjghaO/h8fJ+Sugt4rYoSZbzRDEP3R/cbHT6X+M0b1SfTYuO7EEBgb9UpAEH32hyws= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711711189; c=relaxed/simple; bh=XrtSr/3URoiUtyELhJi9jCK+oBPCwbt9AUgR7MRE+2o=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=hZLGZvIXmiuR/Kdc2m82z2hpv4sVeRTGORIAYN36doATyvN/L8FcUiC/5RH7q5gCJy/PWOS1JXSNk8A10nXJW//OlN3zzdvCgUrHtQ2qxNLWB2ij1Ve/c4e1GIrMkCFRvMZXykrJhUIiXpRCf8eIvT1vDLCNBTVDl9lV8GlTHNY= 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=f8dL1jHg; 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="f8dL1jHg" Received: by mail-wr1-f49.google.com with SMTP id ffacd0b85a97d-341d730bdfcso1643897f8f.1 for ; Fri, 29 Mar 2024 04:19:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1711711185; x=1712315985; 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=tdNi7Qbi3ymn5utM1NA35sC9eXP07A6eygj9yMCfALA=; b=f8dL1jHg4jbTMPQ1LG6LEdwsdCNhGZ3izT3MNtefewT/etRrY7XJwFho5iAowxFfuz ahFIAOWbkHJ+kfWIhmt449T6Yo/SW37h3K8a1lPBKMghFybl+WbP9FhsI7cS718t2xkg DcU8EjRB46ilJaQOumaDRwO63JU8F3XwQ0+Rn8A8RlVgxtCgG5yfEP472zbx1Mtpe/PO 9Gbd/pKbuoC8DfayRVwjSOtzAH63tvlNnBeV7PldLqm96yPCUE2N1JLplm6VRRk7ouwe tViNmrMEviGfxrg05Mgu6j/jKbvkVEHfOpXkQiwORUEK4bV9AgihxxqAb5okxYPx1zBC epaQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1711711185; x=1712315985; 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=tdNi7Qbi3ymn5utM1NA35sC9eXP07A6eygj9yMCfALA=; b=XuwK2Wx3WqN8Ruzh6PKxLFhKTR4ptKkAzpF9txVi9CDY1Zou9kAA/4d/+znWY/D1E4 AF6QwnSAkHgrxPz+/pHV6kzZArfy/VV/wlP7sdKhLvCDt/a/WvBmyDCS1P68dnqC8AP7 vHFVgYGduTZKBtIrvzpq7ItZ9aQE06n6WArH0srAW1Llkl+w3S0ywJtRIMnx7rewLDfa k+MhhkxyUl1hIL+A8gekGAV7pnse6xbeMwqoqmLdmzl6zE2jdMPMC+U3CC6MJAdYUXBR QWB1GaOOAfIx8WhIPJj8dkKlqov9H01H6z3b01LNnJCtTEiDTzcHHWcbrl0NAWrUFvS4 nTKA== X-Gm-Message-State: AOJu0YyrgJwqU9XRgPIYLCg0ARbsFI5PEDh+x9EIkeMdjkp3wiLV4/mc nJlf2Ln/1z/rcQyPWNr96Dw5V5/bK6soJFPCrK7r+5pPHcvl81bW1TvzSwK2 X-Google-Smtp-Source: AGHT+IH9YQ6sjCEY4jjgvT4fPzENIIxyV4wOcLdbzu5YfeQ2tnrgrykDqVk29sl8yW8bvaC719so6A== X-Received: by 2002:adf:f48a:0:b0:33e:6833:8fa9 with SMTP id l10-20020adff48a000000b0033e68338fa9mr1499137wro.44.1711711184781; Fri, 29 Mar 2024 04:19:44 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id by4-20020a056000098400b00341babb8af0sm4011790wrb.7.2024.03.29.04.19.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Mar 2024 04:19:44 -0700 (PDT) Message-Id: <8a25ab1c3b61ebea9942fe106d4e0547a81743a4.1711711181.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Fri, 29 Mar 2024 11:19:37 +0000 Subject: [PATCH v2 1/5] 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: Martin =?utf-8?b?w4VncmVu?= , Jeff King , Eric Sunshine , =?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 | 153 ++++++++++++++++++--------------- 1 file changed, 85 insertions(+), 68 deletions(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 32e69f798ee..ab39509d59d 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,118 @@ 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` + `umask`(2) + + 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, called + unconstrained formatting is required. + Unconstrained formating for placeholders is ____ + Unconstrained formatting for literal formatting is ++like this++ + `--jobs` __ + ++--sort=++____ + ____++/.git++ + ++remote.++____++.mirror++ + + caveat: ++ unconstrained format is not verbatim and may expand + content. Use Asciidoc escapes inside them. - 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. +Synopsis Syntax + + 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++[++=++____] (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 +804,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 Fri Mar 29 11:19:38 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: 13610558 Received: from mail-lj1-f178.google.com (mail-lj1-f178.google.com [209.85.208.178]) (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 D39195A0FB for ; Fri, 29 Mar 2024 11:19:49 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.208.178 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711711191; cv=none; b=RnB49CK229qB8UxzJUx2TGUIEr6zVXwpww+tlvQNmysSBMHbaC3JRP2bRBpKnLhjE5a1LPmA7LwBOX19NSpWprjTTTNy43vwcOWLK9InbBmv/oOluKHkXkHYzRHUeAdiycUDJCAiydFoVIXj+IL6hIhy6ExlMXQLDJGoXj5Dx6s= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711711191; c=relaxed/simple; bh=8enfg2q9CuXi39g3xvOzYmOvYmrXAbZUTaddBmrDfU0=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=aDWG+N+PxRwe2YMBu8B0UmGyXgaaDVJstcf1iRS8B3AXZrruEN4lh3hi32u92MMHq318QEPvaJ4lBogeZlxkxmyvvy9JVOYEWkB4n+YZz6IferOgCTspKeAGtYXgMChhFFxPZBifGPgEhlf6FdAYVluru591Fao8cTXUBN+DZwY= 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=ToX/Gi5P; arc=none smtp.client-ip=209.85.208.178 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="ToX/Gi5P" Received: by mail-lj1-f178.google.com with SMTP id 38308e7fff4ca-2d23114b19dso25544981fa.3 for ; Fri, 29 Mar 2024 04:19:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1711711187; x=1712315987; 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=TUH1t06zi2sSZWyI7qXaaHY4XUZjIy++o7/U9Pxv0VI=; b=ToX/Gi5Py0lZATgSrSnfR/B7rIiYhd4FPFmRJLGm+dC9Jg/VACmduiCYv/KCEgsbpw I3W03vN2FJ1G75c2OoNnROZGWiaKfaxyXKHBR0Q1OrR4vfkP/X6QuQ8YivnMhkVYZpfh /+d7SfUrefhtyGbFr8wak9RzRRbphyvFLaA3JmAJUEU33mK1HV2qrt3OrYgEJvRfhcC2 Zx4ZHrd0nSwY66SuBY7VWVAh5ePXTZ7zV++PaUw6Oj1d4122tqFKK8vAfSyLrrFshbqd 7yPUxFjJeAbtnSwj4fH3cX9zl6HPlXmcolIPPE4FCNMz2CEKDJy5tQoHnvmBi6VT1pYH ixpA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1711711187; x=1712315987; 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=TUH1t06zi2sSZWyI7qXaaHY4XUZjIy++o7/U9Pxv0VI=; b=BZlQC2lpZPEEgGl5OWrd61M8SHkfti6AVZbf2FdEltf9PksGCUP36pzAhMYLx0I5s2 2VktkpAD0FbIDm4DNM6A7f/D0MoUIwAKFA0wUyVZ3eCEmqH4D/haN0NhmoeXj3armWmS uacYBmWjIPywLZhewnQgxyKfyv4/Cus43bnjUXMuY3TMILLEN+IsnS2NqTRjohhwJacA 8Rlo3MEYJfhgZU9S4qcKfkpYlE3ti/MqEuUwFuMsJ8WWCylE3Sl3VBn5WfrvkaBPy86M tsNuH9ia18w5sM6SgiIY3sP8Y2xVa0LWdDjVVfZ4NanQCnLva0OQaGKXie73lR9kzCGT DmPg== X-Gm-Message-State: AOJu0YxxYZwjwAbS98pHNjOeLDd55A+phboOAlUM1/4rHVAOPd7U+fWr jy6M1OxnIHwOFTNLw3WlNEGPee6TS6JcAXRN0yiukanRiB1QjQZEw9m2u2K4 X-Google-Smtp-Source: AGHT+IHtd8H4eTE6h144CJ8JLbSl2yov+af1qsVpF9skbqkFVp5/YudzeBXesbQpYYEdyRHdrzHqBw== X-Received: by 2002:a2e:87ca:0:b0:2d6:ec7b:b69b with SMTP id v10-20020a2e87ca000000b002d6ec7bb69bmr1159446ljj.7.1711711186782; Fri, 29 Mar 2024 04:19:46 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id jb2-20020a05600c54e200b004155387c08esm345552wmb.27.2024.03.29.04.19.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Mar 2024 04:19:45 -0700 (PDT) Message-Id: <1a4feff2aea2e25dc11cbc83f94d0ac6a40964c5.1711711181.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Fri, 29 Mar 2024 11:19:38 +0000 Subject: [PATCH v2 2/5] 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: Martin =?utf-8?b?w4VncmVu?= , Jeff King , Eric Sunshine , =?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 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh index cd3969e852b..69917d7b845 100755 --- a/t/t0450-txt-doc-vs-help.sh +++ b/t/t0450-txt-doc-vs-help.sh @@ -59,7 +59,9 @@ txt_to_synopsis () { -e '/^\[verse\]$/,/^$/ { /^$/d; /^\[verse\]$/d; - + s/_//g; + s/++//g; + s/`//g; s/{litdd}/--/g; s/'\''\(git[ a-z-]*\)'\''/\1/g; From patchwork Fri Mar 29 11:19:39 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: 13610559 Received: from mail-wm1-f47.google.com (mail-wm1-f47.google.com [209.85.128.47]) (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 466906A328 for ; Fri, 29 Mar 2024 11:19:50 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.47 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711711192; cv=none; b=sI9Us5L+9x+ZYmAQTOEleTWhdC1k04VIcjo5hqScUOkTmrmnxzF+hmPmcJixdIczLqIuV9MJC9lp4GDjon9PKB4ftg8QIZr6i1boWhe4r4bh3ZHmbYtAGJ00T+m3rV8A5nJ6fbBYCxV03GBCY/weY2qSYUnGKubE7k4We6ye07I= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711711192; c=relaxed/simple; bh=Z3z6hoexu4De7PPb6veFl353WEPyq7lQxHwGxreiwpk=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=suBlCI8o+z6FWM/0tLDf7VQUGtWJ0Ah7XpC8/EfGO1JbmNuIHk++zorGFAEuvpTCww1wcvtt7ZJux/Lz3hu3wYC2Br9PgWY4/mh4uGVWjXRHVr2BHiCl41zqQrYs+vhbP0bECVxD+q3NZtBhz05bH8ftNxIKdVbDlbOEfRzsuG0= 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=k1SNVWGC; arc=none smtp.client-ip=209.85.128.47 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="k1SNVWGC" Received: by mail-wm1-f47.google.com with SMTP id 5b1f17b1804b1-414925ba716so11337545e9.2 for ; Fri, 29 Mar 2024 04:19:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1711711187; x=1712315987; 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=VWbMMLXM0bYPbwqG/b5bxDhnjdqYdBaEv8zcsk+XyU0=; b=k1SNVWGCALMspJ2U9F4SyCDEPPiud2s04MaNc1AWh6XvgPMspUTTopLiNV2pdeyjdn OLDXRS5+xVc/wDfLbrKRcwLT5MFOhnU0p+lC9P2UlbAFA2JQZGBLLpJ7Q80mt7OwPogf tWRxSKawydUVdXXrpmAOQ3IclgUQdp+jgoDbq0yVFGd7E+rO7Hc//FQKj2XC+Vv1Q8A+ oOf67/slTxXEpv8QI8XTnwMNgp4a2Pq6QB7KIMqumHyqLnxThPGaXO2TojhWOPBMHNeR t4Nq5S3jdxLoU4GCJu3/9Sy56GevzT/aW+mu5URyfA4a11CdvctvWbTq6ZO6+/O/aLds ra1w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1711711187; x=1712315987; 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=VWbMMLXM0bYPbwqG/b5bxDhnjdqYdBaEv8zcsk+XyU0=; b=mE/UHsb9oM/PSzQNXJdHVIw53R7ht4ByquvSbXeurTRwrJXvZmTaZmg85NFnfLtxCG 7vUBecLJulimqx0a2F/QLw86cOJb6OmReqJJemahRE3AoPB3K2cSBmyCNuZYaCC80DkM nVde40CkpsQs7nzVHxrgt9a38MUEkDkCvva/Fjww1PlNEepgukWPDgl3KILFjeDoFeR4 w3hkzWtN/gizh1BVSdRG1+85PLlH15rptnI4dq/TynI7zQpY6Nq4p+YR5rZzD2DHcLBb cYMjJAw+vNpoHyWPJc3sj9v5xNcVb35hRlxO+nNX7A/XD7/iiKjytEyuu8RoyZ1/myzp 5PFQ== X-Gm-Message-State: AOJu0YyUHywSg2FPVVZUqTAi5BNvLHQ2xSkvfq3IvzzPtbPN4mur2H4v moRET+IQFLbUMTgikZiZZlXvEGwIPBwB+7qup2Tb2K73d9RkpqOZSFYGoiEB X-Google-Smtp-Source: AGHT+IEr/CeLDWf+1sMh4lOAToBGbyZqgk2Xz98Re5wRxPBB/31m2SJ0YwkuCNZhMS9JlwBRKIVR6A== X-Received: by 2002:a05:600c:35d6:b0:415:46be:6239 with SMTP id r22-20020a05600c35d600b0041546be6239mr1417666wmq.36.1711711187511; Fri, 29 Mar 2024 04:19:47 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id m31-20020a05600c3b1f00b004146750314csm8313810wms.3.2024.03.29.04.19.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Mar 2024 04:19:47 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Fri, 29 Mar 2024 11:19:39 +0000 Subject: [PATCH v2 3/5] 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: Martin =?utf-8?b?w4VncmVu?= , Jeff King , Eric Sunshine , =?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 | 56 +++++++++++++++++------------------ 2 files changed, 30 insertions(+), 30 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..daff93bd164 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=++____] + [`--separate-git-dir` __] [++--object-format=++____] + [++--ref-format=++____] + [`-b` __ | ++--initial-branch=++____] + [++--shared++[++=++____]] [__] 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=++____:: 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=++____:: Specify the given ref storage __ for the repository. The valid values are: + include::ref-storage-format.txt[] ---template=:: +++--template=++____:: Specify the directory from which templates will be used. (See the "TEMPLATE DIRECTORY" section below.) ---separate-git-dir=:: +++--separate-git-dir=++____:: 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,53 +78,53 @@ repository. + If this is a reinitialization, the repository will be moved to the specified path. --b :: ---initial-branch=:: +`-b` __:: +++--initial-branch=++____:: 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 repository. When specified, the config variable `core.sharedRepository` is set so that files and directories under `$GIT_DIR` are created with the requested permissions. When not specified, Git will use permissions reported -by `umask(2)`. +by `umask`(2). + 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 +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 +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 -otherwise safe umask(2) value. Note that the umask still applies to the other +otherwise safe `umask`(2) value. Note that the umask still applies to the other 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)` +will have mode __. __ will override users' `umask`(2) value (and not only loosen permissions as `group` and `all` do). `0640` will create a repository which is group-readable, but not group-writable or accessible to others. `0660` will create a repo From patchwork Fri Mar 29 11:19:40 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: 13610561 Received: from mail-wm1-f49.google.com (mail-wm1-f49.google.com [209.85.128.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 4E5DB6A356 for ; Fri, 29 Mar 2024 11:19:52 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.49 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711711194; cv=none; b=CwSRwv+aCtCRwHGW61++mdMbcVR9miqUe+V0eqEkjsqvjzlQCze+sw7FrW+5mzCQk7+yV+LP/twVoiqm4iAvW7L/OVs6+VpavLeUQnsn2A63vIhm9SF+9hTZiFa1em7+pTWH5SA3clY/HhMIRQwus6ui2x1WgerKPoo+zo/Q5NM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711711194; c=relaxed/simple; bh=PjSDA40giwmlksrjGH2K68Ln7JHe+/E2EgxjtBIVPxM=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=MfFzhwXDUvQ6TBFKCh3ny+eB6KGhTniMhc7rlV933YRMIBWuSrGd4ksMwqGhtzLOrMY+IZOF3HM08OMLmIdFNzXauH8Yp8eoRWeDZ67IshejAErUX3Owz9Upq80nrXSDMsEdRWMgUG7ntfbV/adTLQwbBljA7aPrkj3I1i1as2A= 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=lrlGTtsA; arc=none smtp.client-ip=209.85.128.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="lrlGTtsA" Received: by mail-wm1-f49.google.com with SMTP id 5b1f17b1804b1-4151d2322caso12324305e9.0 for ; Fri, 29 Mar 2024 04:19:51 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1711711190; x=1712315990; 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=xAzHRV7l+HXfCreqkBUKUrtuZRGvJMPw9Cg0wSG3/Wo=; b=lrlGTtsAnVjqH0qLNhxgGypBayKuCs798KiqreRuSCjfSW2ITe5B94St7ZFd2YKlRc C9g/7iRcZGp7fFpJ+5AA/36NopQVorwbAn9l59i2yfWGBJS2lorMicMTETaE6uDbNrgN FuIrtwL4AadUkAWmuVz97yuWqc1aJ0TtuPJyraUZEMNTdXKhA3T1JnA4oT15SrPq7rDK WnntbOkP5ORDlwSj38BA2XCFB4aMaFCa1K7VMD6Ln1sV/sWzmZKTqHdhFXZ43U+vzy9L bJxrrVhTez1Uqawwrty8xdiGnKxbNzLmpyOM+pBzVDe5y44aEExxpyirOOR+HDJV6CfW 4AwQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1711711190; x=1712315990; 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=xAzHRV7l+HXfCreqkBUKUrtuZRGvJMPw9Cg0wSG3/Wo=; b=aFJ7AyxdQkhpTKJA5DG423ODOvkILmSXyGQQJiFXYZ1Q6G08txx7Iej1WJHqP6xo0n YxZ5LtE/IiznQFtSGyeo7xNP3SSmTn5POAG7OeTAsoArGuNOl6hQMRLTxf0524AbzfDZ jeM8d0LyEp4U55xOr2eLUVAZOmZaewYM6nMo6IPCmBAod2jBCCJCLuPGXcAzfsivI2xb 8H5BO92XRtgrB/8Q6tLBEdbp9EvpWol/oDfOe9q8y/Ery7M8m33o82lBYil4nKyLi7TT IgmW5P8j9YdM+v9Nt/wW8FfgyN6FCh+hL9dwoLsZaqz0gDIRLTYcvySYhJNPpcM3P+5j zqZg== X-Gm-Message-State: AOJu0YwqvwW8za5kqN+Ih7gfAoa+BgSh3HCR48VPE/nynVWGYXJO5AHy tYMMxmyzr+RuQeHB9H6n/8KEnmM7BRbDeObrdukb+BSa0Vf2WxHmO8a6/Bnz X-Google-Smtp-Source: AGHT+IG2OjpNN4Jd+ntorCzlBFC0L+1ypPOYT4EBdbthrlPjnnAKiHI/hyT49XqORDR7KXGdu5tu9Q== X-Received: by 2002:a05:600c:4f0c:b0:414:5e92:cbd8 with SMTP id l12-20020a05600c4f0c00b004145e92cbd8mr1605648wmq.1.1711711189402; Fri, 29 Mar 2024 04:19:49 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id q17-20020a05600c46d100b0041409db0349sm5101122wmo.48.2024.03.29.04.19.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Mar 2024 04:19:47 -0700 (PDT) Message-Id: <54c2012429d5fcc6cf16acaa823e3fc8d9025dbf.1711711182.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Fri, 29 Mar 2024 11:19:40 +0000 Subject: [PATCH v2 4/5] doc: git-clone: 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: Martin =?utf-8?b?w4VncmVu?= , Jeff King , Eric Sunshine , =?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/clone.txt | 6 +- Documentation/git-clone.txt | 120 ++++++++++++++++----------------- Documentation/urls.txt | 44 ++++++------ 3 files changed, 86 insertions(+), 84 deletions(-) diff --git a/Documentation/config/clone.txt b/Documentation/config/clone.txt index d037b57f729..71a967f262d 100644 --- a/Documentation/config/clone.txt +++ b/Documentation/config/clone.txt @@ -1,13 +1,13 @@ -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 option to linkgit:git-clone[1]. -clone.rejectShallow:: +`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..5de18de2ab8 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=++____] + [`-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`]] [`--`] __ + [__] 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=