From patchwork Sat Oct 19 19:59:17 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Kristoffer Haugsbakk X-Patchwork-Id: 13842879 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 6AA5A18D625 for ; Sat, 19 Oct 2024 20:00:11 +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=1729368014; cv=none; b=pJMFWJLSTXI1vql8pYOAyiQlS5o+KBzrvZNMUSKXlgsYA/sTmsk/oO8mtCqy2RTBkGmP6yX/jdKTZfRGMMa3XKCbKwsIakxuuELaGUTobLJHbf4e0pOyazVFk4qJAkNNUGw8JaG7PR51OjefyHaL7JQQwxiBGlf22ZfLsLPa8sw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729368014; c=relaxed/simple; bh=U0CJtzbyXf3vYCgbTJunZITes+tBhoJs0QYiIdpTgpo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=dB5vt29J372NOMKrhs0ph8sPdbogysyEoi76vC42EL14oqktddImaLB7Vc9SaoDl58rizD65PVgtaCaywHsvAOHWCLvqRklOk2LTPfUY/d9fz8c0xSIqgbaiRQ7aNuUuRcDrBQbOAELNXmyMV/h3Pnv5+kuLYPcjSdoaTpMRBm0= 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=nY/c69/c; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=o/x1ljjT; 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="nY/c69/c"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="o/x1ljjT" Received: from phl-compute-10.internal (phl-compute-10.phl.internal [10.202.2.50]) by mailfout.stl.internal (Postfix) with ESMTP id 43C131140095; Sat, 19 Oct 2024 16:00:10 -0400 (EDT) Received: from phl-mailfrontend-02 ([10.202.2.163]) by phl-compute-10.internal (MEProxy); Sat, 19 Oct 2024 16:00:10 -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=fm2; t=1729368010; x=1729454410; bh=0ywGyW6NFmM6mXv16d8pyB7lOImrqh4DnpUdvsSyyr0=; b= nY/c69/ccrN2vPoKHERBw2ROcF/h/dBpvxyItJcuSX/ev7JZ2zym0CI6/qHdYjEO Al3At61LSHu91KMzDUAlbFIPeRLxdlvyEv0YLaMy9J4g5G3H5GOkTNN40MA31Vc/ 64CpZXF5MjHbcVAV1W6AdKJcytmzSfk5PukN4FbjdrMQH8g5KVluazLjimHqbI/A 6wnulkpUTuikuP4LaR6GjjfD29mwzTvP4CjJmMNOtMrbShDTvm1TWWFjYj2gcAgM lE0heMWQgBs5K8JdwtpK8CDuunG9g7cQWAbuQw5kuhI/Dm09x1S0FUunGnTFC1cK U78R70b0J8dMe8zW5m/oOw== 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=fm2; t=1729368010; x= 1729454410; bh=0ywGyW6NFmM6mXv16d8pyB7lOImrqh4DnpUdvsSyyr0=; b=o /x1ljjTKJ/gmkdcB+xJQskcAwIB6Wmf94acWKhPVHrq40YK5uSoISDpSMY0kRyVs lvOOBT5WZTDi0f/8TE0Ccd7RU5/BdoQBuwiwQhK3jwkMTxEnhmCMMQrkbhWd1qb0 mz0ySPjJuev4EcjjygYAZXk6kurqvg/X3pNjm5zJl84MGE7edHIL2WhfDQTA8vmp 5Kp+VWY2VWJUet0CwcY3Tpz099CYQJggB64S8mH5pJDBoanDaqmoQWRDzo8ZRxUd yiyWn3Ur8WoqKXNmtrF5BibEj3f+vSWiQqbx7/Hq9Tv/V6milWqt0IYrwSYVPFWy 4TajZWmUjfI/s5fl+yMaw== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrvdehhedgudegjecutefuodetggdotefrod 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; Sat, 19 Oct 2024 16:00:07 -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 v2 0/6] doc: update-ref: amend old material and discuss symrefs Date: Sat, 19 Oct 2024 21:59:17 +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: fd3c7585a0f84b26debcc216b86dc09acb219799 X-Previous-Commits: 9e775a65eb3ff49ded231aeeeddd59ccdce3c8a8 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 v2 See notes on the patches for all changes. Some of the minor ones are omitted here. • Diff changes (see interdiff): • Fix “the the” • All: Taylor suggested changing the “area” prefix • (but I kept it on the series for consistency) • Link: https://lore.kernel.org/git/ZxAoFUDmdfZ8rlLs@nand.local/ • Patch “drop “flag” ”: • Not done: Wrap paragraph • Patch “remove confusing paragraph” • (Commit) Message tweak • Mention that what a symref is (concretely) is documented elsewhere • Patch “discuss symbolic refs”: • change subject from “symbolic links” • Credit Bence 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 v1: Range-diff against v1: 1: ad9ee00a2a9 ! 1: 91c1cae3209 doc: update-ref: drop “flag” @@ Metadata Author: Kristoffer Haugsbakk ## Commit message ## - doc: update-ref: drop “flag” + Documentation/git-update-ref.txt: drop “flag” - The other paragraphs on options say `With