From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-qt1-f169.google.com (mail-qt1-f169.google.com [209.85.160.169]) (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 818D82E0B5C for ; Fri, 23 Jan 2026 21:15:13 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.160.169 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769202915; cv=none; b=cVwLBr/icIsKXYvcqzNOulIw96Ou3N5Gl21fTlXq6MP+msGUCJZTQ7IV9+LgcQcZ3qdeDxyxyzko8yRLRORQCEtaoy1K+4LeeuqkrWZZ6qJQGNeo/pf3ekFBUskt2J/vhFXL0/3fl4AwUKrUiMw9bOYAFuLRoAxDDdG8Pf3aktU= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769202915; c=relaxed/simple; bh=GxZEPgp5WtCL0RrJn5MxV2aqReReSfox6nUZDGhFtmM=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=OL3VG+TdJH6pJMxUcKREGXYcTTWrIj4LSaL3wuA+Id5rYcEK6cym78H1jl9rkxD17QHKPrnUjSl8KoReI5+u4dS+YTWT0niGfSXuPxWxqop/waPLeOk0ZZ2gco+hdkf2AawRQOZWLMDEXUani70YvRMzqL96lIbEkQSbeCkqlzo= 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=aOWP+gHW; arc=none smtp.client-ip=209.85.160.169 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="aOWP+gHW" Received: by mail-qt1-f169.google.com with SMTP id d75a77b69052e-502a4e3e611so24602081cf.0 for ; Fri, 23 Jan 2026 13:15:13 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1769202912; x=1769807712; 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=1hNzrvRPZ8WJ96Nyyl7SFJaSaVUbigPpQHjCMFc3Vxo=; b=aOWP+gHWphav26dfbkiqDqvhNUaCjgY93MNWfem2p+2tOaF7xzFWNi8BOn9OLsffXP GfIq/yYlb0Ce2Kawv2+5pmCmUMK2jCsNfpl8FjnPRVh2iYwVhrDZcEwuUf4clwY9sBg6 5PhW4Pgca0ONYpbQLQFtUfJim58XumiPWL45VkAXw36+scvODaUsX3EfKCDR9CuZrXt+ 1GJpek98RSEFdzhyHX7X7ZhTJ62HOfBgkkb2LuqVpjIPLwICWuqxiBH54STna7JaXOSq mSCGHZvYqwLNynAuH6nZrX5+KXAKcC0g5mV7kZlR7tBnU+p9oNTFwjDhUgD7JIYyjvQ2 j78w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1769202912; x=1769807712; h=cc:to:fcc:content-transfer-encoding:mime-version:subject:date:from :references:in-reply-to:message-id:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=1hNzrvRPZ8WJ96Nyyl7SFJaSaVUbigPpQHjCMFc3Vxo=; b=ZMRhz85+NDokCJKGNBdxUTVgGXCI4TOn1mehmZGNawADiV0GZWuahNzBQl2UBvJrkO p/JlEAW4h4pajIkv8komUyg+gPIDjLRZWgZxgVZsG1uDDbynvgbL9TXb9FMYXjTrZqa1 qvpDGYpKyfONm81KfYX5ARMoC5ZZed2i6k2wHzWQ1ZrilRXiPh/hZFVOOKbZmziSriJa BexcEMmaQoHxC/Et8f0s+LgyHZeDrWuPlNv5Ef3c2pRW9ruc9UwwIc/De5jYKS8TqvcZ yuGaI6qbi9GnlaDTgqODo7JnPBrNFLgoIQj5TgLjEdUlfi5rHhbsnHC+lnh3S542L1+W ebQA== X-Gm-Message-State: AOJu0YxAAwZRlxlWlEBxO468e+FJlyYu/wx20CsM0Kcu6IFQIWI70Bw5 31IuJ2PqzndlXg0vC7v9JtQ+xvgmbL5rnipYBj4Teg/cXol1gq2ldP4L0PFZ9/2z X-Gm-Gg: AZuq6aKYS9vMHa9PK3ZiBKCKj+SbOrfVepsdzrQtgONVJbKLTzFk+vPnoJgRjT9YOzo uqMV53KQdTECy9goC6uF0Loj9Ou802UGjUHVaVCQEcjBSAcPMi0u+Qhy7qZNFmKzhY89sgaEYSO tCusWpFOtzfP0Lp1h3EgL63KOJWYBPEwalcJQ8ftG4bFHeu0EW5S6AvNSZNo118qCRiM++Wf6ik rDiwEiENn0N2waWPJj/cb8JY1NGRTq/Tv6zfqT9HY+L1TFSQoGe7kLv/F/RPVVd7UMMFvVFhiLU FzTPvvnR0TOkgfPYYGSfKZZZa7Zyh0RmBkcI9BUlwv1fkmw0ks0gM0WbtRrRZyhsoQ31BAbQb7q tjsxK22wPDMXlf6iB111Bxp6U8k6vcqMWeTEs2qfhXUAkA5Oc3oG0261R0hTb6r3cgpCe9oQr6z hQF4fLddK19DZqgnk= X-Received: by 2002:a05:622a:11c3:b0:501:5218:929f with SMTP id d75a77b69052e-502eb5512edmr100153011cf.17.1769202911916; Fri, 23 Jan 2026 13:15:11 -0800 (PST) Received: from [127.0.0.1] ([172.183.133.251]) by smtp.gmail.com with ESMTPSA id d75a77b69052e-502f7f73a62sm24012791cf.16.2026.01.23.13.15.11 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 23 Jan 2026 13:15:11 -0800 (PST) Message-Id: In-Reply-To: References: From: "=?UTF-8?q?Jean-No=C3=ABl=20Avila?= via GitGitGadget" Date: Fri, 23 Jan 2026 21:15:03 +0000 Subject: [PATCH 4/4] doc: convert git-show to synopsis style Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fcc: Sent To: git@vger.kernel.org Cc: =?UTF-8?Q?Jean-No=C3=ABl?= Avila , =?UTF-8?q?Jean-No=C3=ABl=20Avila?= From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= * add synopsis block definition in asciidoc.conf.in * convert commands to synopsis style * use __ for arguments * minor formatting fixes Signed-off-by: Jean-Noël Avila --- Documentation/asciidoc.conf.in | 6 ++ Documentation/git-show.adoc | 16 +-- Documentation/pretty-formats.adoc | 164 +++++++++++++++++------------- 3 files changed, 108 insertions(+), 78 deletions(-) diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in index ff9ea0a294..31b883a72c 100644 --- a/Documentation/asciidoc.conf.in +++ b/Documentation/asciidoc.conf.in @@ -81,12 +81,18 @@ endif::backend-xhtml11[] ifdef::backend-docbook[] ifdef::doctype-manpage[] +[blockdef-open] +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" + [paradef-default] synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" endif::doctype-manpage[] endif::backend-docbook[] ifdef::backend-xhtml11[] +[blockdef-open] +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" + [paradef-default] synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" endif::backend-xhtml11[] diff --git a/Documentation/git-show.adoc b/Documentation/git-show.adoc index 51044c814f..3b180e8c7a 100644 --- a/Documentation/git-show.adoc +++ b/Documentation/git-show.adoc @@ -8,8 +8,8 @@ git-show - Show various types of objects SYNOPSIS -------- -[verse] -'git show' [] [...] +[synopsis] +git show [] [...] DESCRIPTION ----------- @@ -17,16 +17,16 @@ Shows one or more objects (blobs, trees, tags and commits). For commits it shows the log message and textual diff. It also presents the merge commit in a special format as produced by -'git diff-tree --cc'. +`git diff-tree --cc`. For tags, it shows the tag message and the referenced objects. -For trees, it shows the names (equivalent to 'git ls-tree' -with --name-only). +For trees, it shows the names (equivalent to `git ls-tree` +with `--name-only`). For plain blobs, it shows the plain contents. -Some options that 'git log' command understands can be used to +Some options that `git log` command understands can be used to control how the changes the commit introduces are shown. This manual page describes only the most frequently used options. @@ -34,8 +34,8 @@ This manual page describes only the most frequently used options. OPTIONS ------- -...:: - The names of objects to show (defaults to 'HEAD'). +`...`:: + The names of objects to show (defaults to `HEAD`). For a more complete list of ways to spell object names, see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. diff --git a/Documentation/pretty-formats.adoc b/Documentation/pretty-formats.adoc index 2121e8e1df..5b73f03433 100644 --- a/Documentation/pretty-formats.adoc +++ b/Documentation/pretty-formats.adoc @@ -18,54 +18,72 @@ config option to either another format name, or a linkgit:git-config[1]). Here are the details of the built-in formats: -* `oneline` - - +`oneline`:: ++ +[synopsis] +-- +` ` +-- + This is designed to be as compact as possible. -* `short` - - commit - Author: - - - -* `medium` - - commit - Author: - Date: - - +`short`:: ++ +[synopsis] +-- +commit +Author: - + +-- -* `full` +`medium`:: ++ +[synopsis] +-- +commit +Author: +Date: - commit - Author: - Commit: + - + +-- - +`full`:: ++ +[synopsis] +-- +commit +Author: +Commit: -* `fuller` + - commit - Author: - AuthorDate: - Commit: - CommitDate: + +-- - +`fuller`:: ++ +[synopsis] +-- +commit +Author: +AuthorDate: +Commit: +CommitDate: - + -* `reference` + +-- - (, ) +`reference`:: ++ +[synopsis] +-- + (, ) +-- + This format is used to refer to another commit in a commit message and is the same as ++--pretty=\'format:%C(auto)%h (%s, %ad)'++. By default, @@ -74,23 +92,24 @@ is explicitly specified. As with any `format:` with format placeholders, its output is not affected by other options like `--decorate` and `--walk-reflogs`. -* `email` - - From - From: - Date: - Subject: [PATCH] +`email`:: ++ +[synopsis] +-- +From +From: +Date: +Subject: [PATCH] - + +-- -* `mboxrd` -+ +`mboxrd`:: Like `email`, but lines in the commit message starting with "From " (preceded by zero or more ">") are quoted with ">" so they aren't confused as starting a new commit. -* `raw` -+ +`raw`:: The `raw` format shows the entire commit exactly as stored in the commit object. Notably, the hashes are displayed in full, regardless of whether `--abbrev` or @@ -101,8 +120,7 @@ commits are displayed, but not the way the diff is shown e.g. with `git log --raw`. To get full object names in a raw diff format, use `--no-abbrev`. -* `format:` -+ +`format:`:: The `format:` format allows you to specify which information you want to show. It works a little bit like printf format, with the notable exception that you get a newline with `%n` @@ -120,13 +138,18 @@ The title was >>t4119: test autocomputing -p for traditional diff input.<< The placeholders are: - Placeholders that expand to a single literal character: ++ +-- ++%n++:: newline ++%%++:: a raw ++%++ ++%x00++:: ++%x++ followed by two hexadecimal digits is replaced with a byte with the hexadecimal digits' value (we will call this "literal formatting code" in the rest of this document). +-- - Placeholders that affect formatting of later placeholders: ++ +-- ++%Cred++:: switch color to red ++%Cgreen++:: switch color to green ++%Cblue++:: switch color to blue @@ -181,8 +204,11 @@ The placeholders are: ++%><|(++__++)++:: similar to ++%<(++__++)++, ++%<|(++__++)++ respectively, but padding both sides (i.e. the text is centered) +-- - Placeholders that expand to information extracted from the commit: ++ +-- +%H+:: commit hash +%h+:: abbreviated commit hash +%T+:: tree hash @@ -233,36 +259,34 @@ colon and zero or more comma-separated options. Option values may contain literal formatting codes. These must be used for commas (`%x2C`) and closing parentheses (`%x29`), due to their role in the option syntax. -** `prefix=`: Shown before the list of ref names. Defaults to "{nbsp}++(++". -** `suffix=`: Shown after the list of ref names. Defaults to "+)+". -** `separator=`: Shown between ref names. Defaults to "+,+{nbsp}". -** `pointer=`: Shown between HEAD and the branch it points to, if any. - Defaults to "{nbsp}++->++{nbsp}". -** `tag=`: Shown before tag names. Defaults to "`tag:`{nbsp}". +`prefix=`;; Shown before the list of ref names. Defaults to "{nbsp}++(++". +`suffix=`;; Shown after the list of ref names. Defaults to "+)+". +`separator=`;; Shown between ref names. Defaults to "+,+{nbsp}". +`pointer=`;; Shown between HEAD and the branch it points to, if any. + Defaults to "{nbsp}++->++{nbsp}". +`tag=`;; Shown before tag names. Defaults to "`tag:`{nbsp}". + --- For example, to produce decorations with no wrapping or tag annotations, and spaces as separators: - ++ ++%(decorate:prefix=,suffix=,tag=,separator= )++ --- -++%(describe++`[: