From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail.manjaro.org (mail.manjaro.org [116.203.91.91]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D082C13DB8A for ; Thu, 15 Feb 2024 22:28:02 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=116.203.91.91 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1708036086; cv=none; b=D0nYBJFbhW8kllgyqjM6sKnvEnxTysbhajRxmwqC5+V2XP3gb9xvfWZM4RVi8+d1yMKCpfFQmNzADrrtDOnxl3vUo1tpahr2dzpZYyP+7hw0hmfxGOxwAwtXpBomp9LFM6FSRuejwQZAIpeHu9svcsp4Rf9beh2R0EfRYsrE9dI= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1708036086; c=relaxed/simple; bh=HgNodclUfAreujVSo3T4OUtjo+kdeOdpZQRdQRRY0mw=; h=MIME-Version:Date:From:To:Cc:Subject:In-Reply-To:References: Message-ID:Content-Type; b=F4gdr64j2j0YjblC/9lAhppTIFU23AF5RZS0oPstfM5AbchRsBjI0gBgjF3XDQ2nPe0XWZ+nXLZ0k8xypcxmOGBUeXw0w6CFv73Ve+BMalwU80paK4Oc5vuR6VQblDjvEellPpzQsp1jiAATQc0nIm3k6QCsAfOXHKy/wbkKNec= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=manjaro.org; spf=pass smtp.mailfrom=manjaro.org; dkim=pass (2048-bit key) header.d=manjaro.org header.i=@manjaro.org header.b=gpo/OO7m; arc=none smtp.client-ip=116.203.91.91 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=manjaro.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=manjaro.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=manjaro.org header.i=@manjaro.org header.b="gpo/OO7m" Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=manjaro.org; s=2021; t=1708036080; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=nmnRcIJeidhPCJjIZtMXS/wwEOK2zWku8iT/JUyyoP4=; b=gpo/OO7mD1d8aiLG+VmFhEJ8hPvuW6cK2GnOxYO01x8k43N3y2pjIU4/moGIhYMo7Rt4hX aE1QetmP4uo1AwuXGccIXOx4XUImxTQt0EoQxEMlVuMH8BP3BN1gYsLEArpLzCCgCIfg28 8R25SzS70hi5dijSg82cVkzRYJ8tk/K8w0eB4cH34yuaVRBRyRwEZAjhZzbpTrQIkHNm1X u/lBaclFUkrvS6nHKVBk2RdkHXZ4u4ewN7qi5EASewB5YZNYHUMrRYA2GIvp7bduDpxUNH gfqWv65ADREsLpNoFYUGGaFnGz8DIvvWGFaSJayrLSaWRqJnDuVWPyNOJvtrsA== Date: Thu, 15 Feb 2024 23:27:59 +0100 From: Dragan Simic To: =?UTF-8?Q?Rub=C3=A9n_Justo?= Cc: git@vger.kernel.org Subject: Re: [PATCH] branch: rework the descriptions of rename and copy operations In-Reply-To: References: <3cbc78bb5729f304b30bf37a18d1762af553aa00.1708022441.git.dsimic@manjaro.org> Message-ID: <6caad50252bac7f75da8de7e3728a45e@manjaro.org> X-Sender: dsimic@manjaro.org Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit Authentication-Results: ORIGINATING; auth=pass smtp.auth=dsimic@manjaro.org smtp.mailfrom=dsimic@manjaro.org Hello Ruben and Junio, On 2024-02-15 22:52, Rubén Justo wrote: > On 15-feb-2024 19:42:32, Dragan Simic wrote: > >> Move the descriptions of the and arguments to >> the >> descriptions of the branch rename and copy operations, where they >> naturally >> belong. > > Thank you Dragan for working on this. Thank you, and everyone else, for the reviews and suggestions. > Let me chime in just to say that maybe another terms could be > considered > here; like: "" and "" (maybe too long...) > or > so. > > I have no problem with the current terms, but "" can be a > sensible choice here as it is already being used for other commands > where, and this may help overall, the consideration: "if ommited, the > current branch is considered" also applies. Actually, I'd agree with Junio's reply that suggested using even shorter terms. Just like "" and "" can safely be shortened to "" and "", respectively, "" can also be shortened to "". It's all about the context, which is improved by moving the descriptions of the arguments closer to the descriptions of the commands. Though, I'd prefer that we keep "" and "" (and "") for now, for the sake of consistency, and I'd get them shortened in the future patches. >> Also, improve the descriptions of these two branch operations and, >> for completeness, describe the outcomes of forced operations. >> >> Describing the arguments together with their respective operations, >> instead >> of describing them separately in a rather unfortunate attempt to >> squeeze more >> meaning out of fewer words, flows much better and makes the >> git-branch(1) >> man page significantly more usable. >> >> The subsequent improvements shall continue this approach by either >> dissolving >> as many sentences from the "Description" section into the "Options" >> section, >> or by having those sentences converted into some kind of more readable >> and >> better flowing prose, as already discussed and outlined. [1][2] >> >> [1] https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/T/#u >> [2] https://lore.kernel.org/git/xmqq8r4zln08.fsf@gitster.g/T/#u >> >> Signed-off-by: Dragan Simic >> --- >> >> Notes: >> This patch was originally named "branch: clarify and >> >> terms further", submitted and discussed in another thread, [3] but >> the nature >> of the patch has changed, causing the patch subject to be adjusted >> to match. >> >> Consequently, this is effectively version 2 of the patch, which >> includes >> detailed feedback from Kyle and Junio, who suggested moving/adding >> the >> argument descriptions to their respective commands. This resulted >> in more >> significant changes to the contents of the git-branch(1) man page, >> in an >> attempt to make it more readable. >> >> [3] >> https://lore.kernel.org/git/e2eb777bca8ffeec42bdd684837d28dd52cfc9c3.1707136999.git.dsimic@manjaro.org/T/#u >> >> Documentation/git-branch.txt | 44 >> +++++++++++++++--------------------- >> 1 file changed, 18 insertions(+), 26 deletions(-) >> >> diff --git a/Documentation/git-branch.txt >> b/Documentation/git-branch.txt >> index 0b0844293235..370ea43c0380 100644 >> --- a/Documentation/git-branch.txt >> +++ b/Documentation/git-branch.txt >> @@ -72,16 +72,6 @@ the remote-tracking branch. This behavior may be >> changed via the global >> overridden by using the `--track` and `--no-track` options, and >> changed later using `git branch --set-upstream-to`. >> >> -With a `-m` or `-M` option, will be renamed to >> . >> -If had a corresponding reflog, it is renamed to match >> -, and a reflog entry is created to remember the branch >> -renaming. If exists, -M must be used to force the rename >> -to happen. >> - >> -The `-c` and `-C` options have the exact same semantics as `-m` and >> -`-M`, except instead of the branch being renamed, it will be copied >> to a >> -new name, along with its config and reflog. >> - >> With a `-d` or `-D` option, `` will be deleted. You may >> specify more than one branch for deletion. If the branch currently >> has a reflog then the reflog will also be deleted. >> @@ -128,18 +118,28 @@ Note that 'git branch -f >> []', even with '-f', >> refuses to change an existing branch `` that is checked >> out >> in another worktree linked to the same repository. >> >> --m:: >> ---move:: >> - Move/rename a branch, together with its config and reflog. >> +-m [] :: >> +--move [] :: >> + Rename an existing branch , which if not specified >> defaults >> + to the current branch, to . The configuration variables >> + for the branch and its reflog are also renamed >> appropriately >> + to be used with . Renaming fails if branch >> + already exists, but you can use `-M` or `--move --force` to >> overwrite >> + the files in existing branch while renaming. >> >> --M:: >> +-M [] :: >> Shortcut for `--move --force`. >> >> --c:: >> ---copy:: >> - Copy a branch, together with its config and reflog. >> +-c [] :: >> +--copy [] :: >> + Copy an existing branch , which if not specified defaults >> + to the current branch, to . The configuration variables >> + for the branch and its reflog are also copied >> appropriately >> + to be used with . Copying fails if branch >> + already exists, but you can use `-C` or `--copy --force` to >> overwrite >> + the files in existing branch while copying. >> >> --C:: >> +-C [] :: >> Shortcut for `--copy --force`. >> >> --color[=]:: >> @@ -311,14 +311,6 @@ superproject's "origin/main", but tracks the >> submodule's "origin/main". >> given as a branch name, a commit-id, or a tag. If this >> option is omitted, the current HEAD will be used instead. >> >> -:: >> - The name of an existing branch. If this option is omitted, >> - the name of the current branch will be used instead. >> - >> -:: >> - The new name for an existing branch. The same restrictions as for >> - apply. >> - >> --sort=:: >> Sort based on the key given. Prefix `-` to sort in descending >> order of the value. You may use the --sort= option