From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from fout-b7-smtp.messagingengine.com (fout-b7-smtp.messagingengine.com [202.12.124.150]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 53FD3247DE1 for ; Mon, 16 Mar 2026 21:49:56 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=202.12.124.150 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773697797; cv=none; b=FKFb2AqZGI3WV7WmtJxYRfCaG2VW/rUg2VZiT2oIqCBPQ/dHNSFlntgkK9OVvO9s9LbMrBT7fcKqrgcxXto/W2bA1YEFI86t37PaUPM8/39pob8UAimWdJJ/HXKy57aAMzbQ7tONc1v44PeaOF3qPfeXU5X07hVXwziEkUjFqpY= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773697797; c=relaxed/simple; bh=fIS7/mHoczeZG5LVPS/4BuChxEXcbXbLk+7+LwPi5eE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=sYyw2C3RU1LC20LhdkFuz7wcLjyy69JcbYmT5ITeCtFePl1I0VyOZZZTC05PhZ9DOCmFT1iAvWqGWdZUqJjMK2suIWy0pchRv3YGvPTzMPji7p8OhR5zNwpeJ/+3X0qrRd+/V9n1M7FeK9pIu7ipZJGfXDHv3siefO29kKE/GvU= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=fastmail.com; spf=pass smtp.mailfrom=fastmail.com; dkim=pass (2048-bit key) header.d=fastmail.com header.i=@fastmail.com header.b=WCwLA0Ul; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=L1eDrNN+; arc=none smtp.client-ip=202.12.124.150 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=fastmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=fastmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=fastmail.com header.i=@fastmail.com header.b="WCwLA0Ul"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="L1eDrNN+" Received: from phl-compute-04.internal (phl-compute-04.internal [10.202.2.44]) by mailfout.stl.internal (Postfix) with ESMTP id 9A73C1D002EF; Mon, 16 Mar 2026 17:49:55 -0400 (EDT) Received: from phl-frontend-03 ([10.202.2.162]) by phl-compute-04.internal (MEProxy); Mon, 16 Mar 2026 17:49:55 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=fastmail.com; h= cc:cc:content-transfer-encoding:content-type:content-type:date :date:from:from:in-reply-to:in-reply-to:message-id:mime-version :references:reply-to:subject:subject:to:to; s=fm1; t=1773697795; x=1773784195; bh=f97Nqsbq7cyG1i8aFh1SQ3hoxAH6yi7UCqKRS950/vg=; b= WCwLA0UlGEmZ4YPYvij1iFJH2eqdPNXk+JSfkT5bcs6ujESVvwIgBkdGAtFz/V/W T9UqBBabMESb8qdoQp8mdgerHFF7Q8n8uLE4SzVp10z0NToJLWLS0nUF5plsWpq3 aRBflV1SLsl7NSaMLQFc58X1U9fy9UssYFTCGnpAog+uDk84CD6QNZmkaxMfyJUG 5WLdO7/wXpUIVHelX8QMp0ptXpmcTOiW0pMTi0yCl44eq8/AnQrxqQXsDdgclTTo +58m23DlkYqKj4Lgdo8feu6rqFY+B2o1kO0TQKgJsLDkNl3JMun41C+SzHcha3MU JAfdeR61Qh2x+2BAO7m6AA== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-transfer-encoding :content-type:content-type:date:date:feedback-id:feedback-id :from:from:in-reply-to:in-reply-to:message-id:mime-version :references:reply-to:subject:subject:to:to:x-me-proxy :x-me-sender:x-me-sender:x-sasl-enc; s=fm1; t=1773697795; x= 1773784195; bh=f97Nqsbq7cyG1i8aFh1SQ3hoxAH6yi7UCqKRS950/vg=; b=L 1eDrNN+fxHLrf5BCQXhUYB0yADHgnA4Zr1rGWNRbVCLan+B6BxBby5kBf/mguWQG eul9OElvZC8x+8dAHSFpWnKqY9riIqAqYz9LfM8WAoHHp+1j6REswESoMfc8p7mQ /UlWtvAql5ACWdv6WuWBtZZFP48qn+leo02iE2TzZo7EsshCerngEp6dP3xbP415 6DaabYQD7FfHPl44F0HL66QcRWA8p3x4vXKMlDZhhCCsaDi7MY8oprutlFuXaUbc cxxH2sg9isOUMmWhSqk5vGuGwNUfRuwYyZe46nvrkEHz2oCvjq+9UbXd6jyWOXyc eLjoXI6QcpUOb9a45VVwg== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeefgedrtddtgddvleelhedtucetufdoteggodetrf dotffvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfurfetoffkrfgpnffqhgenuceu rghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmnegfrh hlucfvnfffucdlfeehmdenucfjughrpefhvfevufffkffojghfgggtgfesthekredtredt jeenucfhrhhomhepkhhrihhsthhofhhfvghrhhgruhhgshgsrghkkhesfhgrshhtmhgrih hlrdgtohhmnecuggftrfgrthhtvghrnhephffggeelhfejkefgteelteejhfetieehgeef tdduudffgeejhfektedugefghfeknecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrg hmpehmrghilhhfrhhomhepkhhrihhsthhofhhfvghrhhgruhhgshgsrghkkhesfhgrshht mhgrihhlrdgtohhmpdhnsggprhgtphhtthhopeefpdhmohguvgepshhmthhpohhuthdprh gtphhtthhopehgihhtsehvghgvrhdrkhgvrhhnvghlrdhorhhgpdhrtghpthhtoheptgho uggvsehkhhgruhhgshgsrghkkhdrnhgrmhgvpdhrtghpthhtohepjhhnrdgrvhhilhgrse hfrhgvvgdrfhhr X-ME-Proxy: Feedback-ID: i8b11424c:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Mon, 16 Mar 2026 17:49:54 -0400 (EDT) From: kristofferhaugsbakk@fastmail.com To: git@vger.kernel.org Cc: Kristoffer Haugsbakk , =?UTF-8?q?Jean-No=C3=ABl=20Avila?= Subject: [PATCH v2 3/4] doc: config: convert trailers section to synopsis style Date: Mon, 16 Mar 2026 22:48:26 +0100 Message-ID: X-Mailer: git-send-email 2.53.0.32.gf6228eaf9cc In-Reply-To: References: 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 From: Kristoffer Haugsbakk Convert this part of the configuration documentation to synopsis style so that all of git-interpret-trailers(1) is consistent. See the commit message from two commits ago. Signed-off-by: Kristoffer Haugsbakk --- Notes (series): v2: • → (no camelcase) • Refer to two-commits-ago for an explanation of the changes Documentation/config/trailer.adoc | 121 +++++++++++++++--------------- 1 file changed, 61 insertions(+), 60 deletions(-) diff --git a/Documentation/config/trailer.adoc b/Documentation/config/trailer.adoc index 60bc221c88b..1bc70192d3a 100644 --- a/Documentation/config/trailer.adoc +++ b/Documentation/config/trailer.adoc @@ -1,21 +1,21 @@ -trailer.separators:: +`trailer.separators`:: This option tells which characters are recognized as trailer - separators. By default only ':' is recognized as a trailer - separator, except that '=' is always accepted on the command + separators. By default only `:` is recognized as a trailer + separator, except that `=` is always accepted on the command line for compatibility with other git commands. + The first character given by this option will be the default character used when another separator is not specified in the config for this trailer. + -For example, if the value for this option is "%=$", then only lines -using the format '' with containing '%', '=' -or '$' and then spaces will be considered trailers. And '%' will be +For example, if the value for this option is `%=$`, then only lines +using the format __ with __ containing `%`, `=` +or `$` and then spaces will be considered trailers. And `%` will be the default separator used, so by default trailers will appear like: -'% ' (one percent sign and one space will appear between +`% ` (one percent sign and one space will appear between the key and the value). -trailer.where:: +`trailer.where`:: This option tells where a new trailer will be added. + This can be `end`, which is the default, `start`, `after` or `before`. @@ -27,41 +27,41 @@ If it is `start`, then each new trailer will appear at the start, instead of the end, of the existing trailers. + If it is `after`, then each new trailer will appear just after the -last trailer with the same . +last trailer with the same __. + If it is `before`, then each new trailer will appear just before the -first trailer with the same . +first trailer with the same __. -trailer.ifexists:: +`trailer.ifexists`:: This option makes it possible to choose what action will be performed when there is already at least one trailer with the - same in the input. + same __ in the input. + The valid values for this option are: `addIfDifferentNeighbor` (this is the default), `addIfDifferent`, `add`, `replace` or `doNothing`. + With `addIfDifferentNeighbor`, a new trailer will be added only if no -trailer with the same (, ) pair is above or below the line +trailer with the same (__, __) pair is above or below the line where the new trailer will be added. + With `addIfDifferent`, a new trailer will be added only if no trailer -with the same (, ) pair is already in the input. +with the same (__, __) pair is already in the input. + With `add`, a new trailer will be added, even if some trailers with -the same (, ) pair are already in the input. +the same (__, __) pair are already in the input. + -With `replace`, an existing trailer with the same will be +With `replace`, an existing trailer with the same __ will be deleted and the new trailer will be added. The deleted trailer will be -the closest one (with the same ) to the place where the new one +the closest one (with the same __) to the place where the new one will be added. + With `doNothing`, nothing will be done; that is no new trailer will be -added if there is already one with the same in the input. +added if there is already one with the same __ in the input. -trailer.ifmissing:: +`trailer.ifmissing`:: This option makes it possible to choose what action will be performed when there is not yet any trailer with the same - in the input. + __ in the input. + The valid values for this option are: `add` (this is the default) and `doNothing`. @@ -70,67 +70,68 @@ With `add`, a new trailer will be added. + With `doNothing`, nothing will be done. -trailer..key:: - Defines a for the . The must be a - prefix (case does not matter) of the . For example, in `git - config trailer.ack.key "Acked-by"` the "Acked-by" is the and - the "ack" is the . This configuration allows the shorter +`trailer..key`:: + Defines a __ for the __. The __ must be a + prefix (case does not matter) of the __. For example, in `git + config trailer.ack.key "Acked-by"` the `Acked-by` is the __ and + the `ack` is the __. This configuration allows the shorter `--trailer "ack:..."` invocation on the command line using the "ack" - instead of the longer `--trailer "Acked-by:..."`. + `` instead of the longer `--trailer "Acked-by:..."`. + -At the end of the , a separator can appear and then some -space characters. By default the only valid separator is ':', +At the end of the __, a separator can appear and then some +space characters. By default the only valid separator is `:`, but this can be changed using the `trailer.separators` config variable. + If there is a separator in the key, then it overrides the default separator when adding the trailer. -trailer..where:: - This option takes the same values as the 'trailer.where' +`trailer..where`:: + This option takes the same values as the `trailer.where` configuration variable and it overrides what is specified by - that option for trailers with the specified . + that option for trailers with the specified __. -trailer..ifexists:: - This option takes the same values as the 'trailer.ifexists' +`trailer..ifexists`:: + This option takes the same values as the `trailer.ifexists` configuration variable and it overrides what is specified by - that option for trailers with the specified . + that option for trailers with the specified __. -trailer..ifmissing:: - This option takes the same values as the 'trailer.ifmissing' +`trailer..ifmissing`:: + This option takes the same values as the `trailer.ifmissing` configuration variable and it overrides what is specified by - that option for trailers with the specified . + that option for trailers with the specified __. -trailer..command:: - Deprecated in favor of 'trailer..cmd'. - This option behaves in the same way as 'trailer..cmd', except +`trailer..command`:: + Deprecated in favor of `trailer..cmd`. + This option behaves in the same way as `trailer..cmd`, except that it doesn't pass anything as argument to the specified command. - Instead the first occurrence of substring $ARG is replaced by the - that would be passed as argument. + Instead the first occurrence of substring `$ARG` is replaced by the + __ that would be passed as argument. + -Note that $ARG in the user's command is -only replaced once and that the original way of replacing $ARG is not safe. +Note that `$ARG` in the user's command is +only replaced once and that the original way of replacing `$ARG` is not safe. + -When both 'trailer..cmd' and 'trailer..command' are given -for the same , 'trailer..cmd' is used and -'trailer..command' is ignored. +When both `trailer..cmd` and `trailer..command` are given +for the same __, `trailer..cmd` is used and +`trailer..command` is ignored. -trailer..cmd:: +`trailer..cmd`:: This option can be used to specify a shell command that will be called - once to automatically add a trailer with the specified , and then - called each time a '--trailer =' argument is specified to - modify the of the trailer that this option would produce. + once to automatically add a trailer with the specified __, and then + called each time a `--trailer =` argument is specified to + modify the __ of the trailer that this option would produce. + When the specified command is first called to add a trailer -with the specified , the behavior is as if a special -'--trailer =' argument was added at the beginning -of the "git interpret-trailers" command, where -is taken to be the standard output of the command with any -leading and trailing whitespace trimmed off. +with the specified __, the behavior is as if a special +`--trailer =` argument was added at the beginning +of linkgit:git-interpret-trailers[1], where __ is taken to be the +standard output of the command with any leading and trailing whitespace +trimmed off. + -If some '--trailer =' arguments are also passed +If some `--trailer =` arguments are also passed on the command line, the command is called again once for each -of these arguments with the same . And the part +of these arguments with the same __. And the __ part of these arguments, if any, will be passed to the command as its -first argument. This way the command can produce a computed -from the passed in the '--trailer =' argument. +first argument. This way the command can produce a __ computed +from the __ passed in the `--trailer =` +argument. -- 2.53.0.32.gf6228eaf9cc