From patchwork Mon Oct 21 20:47:23 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Kristoffer Haugsbakk X-Patchwork-Id: 13844667 Received: from fhigh-a5-smtp.messagingengine.com (fhigh-a5-smtp.messagingengine.com [103.168.172.156]) (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 BEC4816A92E for ; Mon, 21 Oct 2024 20:47:51 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=103.168.172.156 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729543674; cv=none; b=mVtoqdndHNRLAk2x/95D2Tug9n4XA6CRg08m5W0guv+2PcSBcDxy58YA6fUvMT7x3ZBHpUzh5TZg+P/K/5AoqbsJah/t76LiD1DCPufZ6+Xw7RQe8r7oFYz1y8jz/VE2IYlQF2el5yvg76K9DADo5HSygiJTJKlTlWLWdAGWnFo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729543674; c=relaxed/simple; bh=xvoWRZKHww/8qc3DhGxtrZ9anh5juUdXO+eV23VZRHY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=AqAXWoBKbpUtgD0WMMU17ZnDkayDg1FOHI1YhMiaeEPjbGQk5cWOYIUEaASXQmTgZzXO6o6KpKZrXEgVazxwY5TgdFaQuBN40Trh+rGYG+fbLMokyi/6LFHUzP9abuM4Wqi5nRH5SnARIqENm2tGj2J2AoxwblFhFU3jLE5dfes= 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=qGYSruxN; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=TCon3ytZ; arc=none smtp.client-ip=103.168.172.156 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="qGYSruxN"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="TCon3ytZ" Received: from phl-compute-08.internal (phl-compute-08.phl.internal [10.202.2.48]) by mailfhigh.phl.internal (Postfix) with ESMTP id B2A1111401E2; Mon, 21 Oct 2024 16:47:50 -0400 (EDT) Received: from phl-mailfrontend-01 ([10.202.2.162]) by phl-compute-08.internal (MEProxy); Mon, 21 Oct 2024 16:47:50 -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=fm3; t=1729543670; x=1729630070; bh=AlBL4yq69z+cvcPZCmSL9kt0jOFgGtSolKY7euGkI9I=; b= qGYSruxNCiCSQwIoASRMhVKnFjoA5qQCB8XPW2IxI0P0yldKowqMLRReG0raRwC8 JO4KxUGxWW8F2zOEksnpk9NMAwA6Zqy6quWncV4D4DsKCBF6CYHCA1/SzHCTWl6h 01tNMNUAegXABRfDqCHsmFZ832v5/O3ZnGTbj9/ZxrdFzBKI6QY54MjakXjAs8gN 0jObn6WJd1VFybE3d/0A9pjKknMkU89TJuPwcy+zng7awbtYaillFuWJpjspImfr OPIZh/SxiCCt+dMPvZq6uLSJg3gQiZ8gC5hK1h8WypVnZHA77mCcoF89P2MlZH7a bMLC155YqTihQzEQY8aKAg== 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-proxy :x-me-sender:x-me-sender:x-sasl-enc; s=fm3; t=1729543670; x= 1729630070; bh=AlBL4yq69z+cvcPZCmSL9kt0jOFgGtSolKY7euGkI9I=; b=T Con3ytZFEGUFSLvNLZIFf8MSYrODoWst/r15UkRzQjff3oknxfZqVPl+R7sBQxuX aAqsFgx89yoQ3UGuY74fYAuxuaeksOK5KErH1hL91qyFZztZRYgoKsZEq+BFNUWM I8IgHVBgTDJHQ0NcT9bXCGeIw0UDyxDcbUa3fmVq4MLGCuBSUiu/d5Ji85mui0Al bNKJXmfMgZquJ+bWQCYSMHAuKceT7D6dEULW04TEDWnHoDfEAmHt6zqXl5+EnV8o kJp0Kvd7CzOo6UeOXlKgz+Koc0eP33kuDlZIz69+f2fr2yKSnfMPmDsRCcxMs9wv egWpABdikZMNxaw4ys14Q== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrvdehledgudehgecutefuodetggdotefrod ftvfcurfhrohhfihhlvgemucfhrghsthforghilhdpggftfghnshhusghstghrihgsvgdp uffrtefokffrpgfnqfghnecuuegrihhlohhuthemuceftddtnecunecujfgurhephffvve fufffkofgjfhggtgfgsehtkeertdertdejnecuhfhrohhmpehkrhhishhtohhffhgvrhhh rghughhssggrkhhksehfrghsthhmrghilhdrtghomhenucggtffrrghtthgvrhhnpedule fgueeiueetkeelieefgedufeehteekhfejffekvdeuhedtvefhkeeikefhgfenucffohhm rghinhepkhgvrhhnvghlrdhorhhgnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrg hmpehmrghilhhfrhhomhepkhhrihhsthhofhhfvghrhhgruhhgshgsrghkkhesfhgrshht mhgrihhlrdgtohhmpdhnsggprhgtphhtthhopeekpdhmohguvgepshhmthhpohhuthdprh gtphhtthhopehgihhtsehvghgvrhdrkhgvrhhnvghlrdhorhhgpdhrtghpthhtoheptgho uggvsehkhhgruhhgshgsrghkkhdrnhgrmhgvpdhrtghpthhtohepphhhihhllhhiphdrfi hoohguseguuhhnvghlmhdrohhrghdruhhkpdhrtghpthhtohepghhithhsthgvrhesphho sghogidrtghomhdprhgtphhtthhopegsvghntggvsehfvghrughinhgrnhguhidrtghomh dprhgtphhtthhopehkrghrthhhihhkrddukeeksehgmhgrihhlrdgtohhmpdhrtghpthht ohepmhgvsehtthgrhihlohhrrhdrtghomhdprhgtphhtthhopehsuhhnshhhihhnvgessh hunhhshhhinhgvtghordgtohhm X-ME-Proxy: Feedback-ID: i8b11424c:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Mon, 21 Oct 2024 16:47:47 -0400 (EDT) From: kristofferhaugsbakk@fastmail.com To: git@vger.kernel.org Cc: Kristoffer Haugsbakk , phillip.wood@dunelm.org.uk, gitster@pobox.com, bence@ferdinandy.com, karthik.188@gmail.com, me@ttaylorr.com, sunshine@sunshineco.com Subject: [PATCH v3 0/6] doc: update-ref: amend old material and discuss symrefs Date: Mon, 21 Oct 2024 22:47:23 +0200 Message-ID: X-Mailer: git-send-email 2.46.1.641.g54e7913fcb6 In-Reply-To: References: Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Commit-Hash: aa1ee4a8ee08f623b2b85f68a141f188364243f4 X-Previous-Commits: 9e775a65eb3ff49ded231aeeeddd59ccdce3c8a8 fd3c7585a0f84b26debcc216b86dc09acb219799 From: Kristoffer Haugsbakk This series removes or moves some old material in the update-ref doc and improves the discussion of symrefs, opting for a high-level description with some redundancy (see patch 5/6) in order to avoid a reported mistake/confusion. The end goal (after all patches are applied): • First paragraph (in Description) describes the first form • Second paragraph the second form • Third paragraph mentions symrefs and explains why `--stdin` supports them • A new section whither the symlink (FS) vs. symrefs discussion is moved • Link update-ref to symbolic-ref and vice versa § Changes in v3 • Diff changes (see interdiff): • Add missing word “that” • Patch “remove confusing paragraph” • Rewrite message to emphasize ref backends • Patch “drop “flag” ”: • Add missing word “that” Kristoffer Haugsbakk (6): Documentation/git-update-ref.txt: drop “flag” Documentation/git-update-ref.txt: remove safety paragraphs Documentation/git-update-ref.txt: demote symlink to last section Documentation/git-update-ref.txt: remove confusing paragraph Documentation/git-update-ref.txt: discuss symbolic refs Documentation: mutually link update-ref and symbolic-ref Documentation/git-symbolic-ref.txt | 4 +++ Documentation/git-update-ref.txt | 48 +++++++++++++----------------- 2 files changed, 25 insertions(+), 27 deletions(-) Interdiff against v2: Range-diff against v2: 1: 91c1cae3209 ! 1: 9c40351950f Documentation/git-update-ref.txt: drop “flag” @@ Commit message The other paragraphs on options say “With