From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-dy1-f174.google.com (mail-dy1-f174.google.com [74.125.82.174]) (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 AC34F314D14 for ; Tue, 3 Feb 2026 17:03:47 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=74.125.82.174 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1770138231; cv=none; b=Cfhz4hrMNzh8hh4O6HQChrUqZCZbR4dLnAjZIaz9/ZtqxdvWwgZ6LmWy0P4kL4RIDr4iZhhtGMrvSHzQIPO2QDm8nu1oOBqxlBCTnhlv3f+CXq8MWSzUJ8/QL40v9McyTxiaovQ7L/AM+8+Pfnwx+jWzjP6gtX8mAkrkQJUjvAE= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1770138231; c=relaxed/simple; bh=u3d2KwUjvL+LepAXy/b2Seg1D1PcDtKAqJQOxpnAq28=; h=Message-Id:In-Reply-To:References:From:Date:Subject:MIME-Version: Content-Type:To:Cc; b=edAaIdVS7RWdlLwgjIywFOB5DTjUwD3sPVDUSf3UosRUY1YMHkjpwinrbB1Rml8IEANobizWNr1VygI5CevZgeHteo5DyGoj7fx3cHoJzWTOYX7rb9bvAMjZ3yRNWitekf2p0nUx3xUSgyESzbdooCFAacLdEvrhd/ymikjA7is= 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=f5it0V7w; arc=none smtp.client-ip=74.125.82.174 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="f5it0V7w" Received: by mail-dy1-f174.google.com with SMTP id 5a478bee46e88-2b82c605dbdso629784eec.0 for ; Tue, 03 Feb 2026 09:03:46 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1770138225; x=1770743025; 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=BHak0funCF6mdYfg1zC8cCDJWgVvrmgTSbImASzT9ws=; b=f5it0V7wV3dUW/QGuf7/Lr//20FxuCtTh5IHTt7bovrLkaJKG7npQXQqz7Ez6xNYyF Z4EYufuMdUosTrrNXBux/Ly5u+ZQee4zMoxx7JsnqBb8qIQ9Ocej/7/KUzfB4BCnCvAx TTbSMf6LoA3tCihJIdUnxfxcRQqIBmFutyr6Og9FHJ4bbTqynTFBcuKzbLY3BelYHi0H 5jXHYttENU5/1DtvfwSVq2+LqiwxJJ8RW6Q1wl/7HxgMJ4wavbe4jANFmiIQfd9RRs0i WkeMVq76Ry0/9ii1xZqmErMEG+Fnp3aJ7/27aR4zZtRp1zFQo8MWpR075EhRKTrBsH3b zlHA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1770138225; x=1770743025; 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=BHak0funCF6mdYfg1zC8cCDJWgVvrmgTSbImASzT9ws=; b=XgrCTkby9xV7jLue2sA+QZ5Su8oxIg7q8Wvgi0PdzgeMD7e6oS7OwJfTiabWV/GSH8 n0qP5x5tWs9bJBM14hYn6u9WVL//tJMRRKdrcDfegayDng3snyjeYvs+OvnlM/5Nk4pX xXQDJMeRKzHp+Fvojps2Ujv89yTTaBeA4dmr2hLYUW95wg0ivH+wpcZedO7T8Yq6uXmk AvuvbnnwfRIgR7mWKQ/QvcfnP2ERCYMhggTa4LSoJL0PIqj9eIoGOcRU2FmChqLaRKAV 7KSI7TXiPYsw2xyIpX/WgPMn/CK3TGm4474DpBvBD3qHONDU+MNAEO1E7vwtib3ezA0+ qNGA== X-Gm-Message-State: AOJu0Yy4cu0275KWB5h3nmevpeZTTZ7kG3ghuYPVDyRN7+2DVsWR4WLx 2HpUEIla4OgDRJ4ewjWnpgaS6Oy5QCL1RaMfyiyuoZaaGhJVW5fhzHpkW2mu9q2l X-Gm-Gg: AZuq6aIUbfewAdVBwr3ZoJvdJAY1q1zEJbffVOCswsg+vYo92ISQYmRCeEkajMGjZ0F t3DgJOVHJa7CRnMa+MaTuHjQbtAfbI2V23huz3loadD279TRKIXiQeUV/LEMTISW7COBA/zr09g iBJl4xQhqajR9Wryt0zOQjYU5lgNM2kayHuvtG4duPn+SKTkDFGAuXZXzaIkctrVhkuYK/363xv Dpwuc6CtLWWFRR0Qc5VMZO02zvqfJzcXO7+0kvhSkOAuP0gYcP9n2FRvS4tGnc2sMhyaAKL/ntG LyvVHNwMI77QxC2laJXWP4f1dGhuErZ4vNdMZcqg7EQIj10Xs5pPfl0LNbBFO5wfzRgq/fV8ATW ulaFnai+0WjJICgG0bJtIJBnhybio+6Bd/6ICXMXpThLU1qqxUdHFcgZpJBNsf5FnB0LxXr2Q2H VRK3OwiX7mMCyn X-Received: by 2002:a05:7300:a54c:b0:2ae:5b01:bfa5 with SMTP id 5a478bee46e88-2b8329d9434mr81969eec.32.1770138224897; Tue, 03 Feb 2026 09:03:44 -0800 (PST) Received: from [127.0.0.1] ([20.169.75.197]) by smtp.gmail.com with ESMTPSA id 5a478bee46e88-2b832faea55sm27996eec.23.2026.02.03.09.03.43 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 03 Feb 2026 09:03:44 -0800 (PST) Message-Id: In-Reply-To: References: From: "=?UTF-8?q?Jean-No=C3=ABl=20Avila?= via GitGitGadget" Date: Tue, 03 Feb 2026 17:03:35 +0000 Subject: [PATCH v3 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: Kristoffer Haugsbakk , =?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 Reviewed-by: Kristoffer Haugsbakk --- Documentation/asciidoc.conf.in | 6 ++ Documentation/git-show.adoc | 16 +-- Documentation/pretty-formats.adoc | 169 +++++++++++++++++------------- 3 files changed, 111 insertions(+), 80 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..5405e57a60 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,20 +259,19 @@ 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= )++ --- +--------------------- + %(decorate:prefix=,suffix=,tag=,separator= ) +--------------------- ++%(describe++`[: