From patchwork Fri Dec 15 20:32:41 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Junio C Hamano X-Patchwork-Id: 13494876 Received: from pb-smtp21.pobox.com (pb-smtp21.pobox.com [173.228.157.53]) (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 5A10047F43 for ; Fri, 15 Dec 2023 20:32:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=pobox.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pobox.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=pobox.com header.i=@pobox.com header.b="ssUkjhRi" Received: from pb-smtp21.pobox.com (unknown [127.0.0.1]) by pb-smtp21.pobox.com (Postfix) with ESMTP id B127A27BAD; Fri, 15 Dec 2023 15:32:53 -0500 (EST) (envelope-from gitster@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to:cc :subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; s=sasl; bh=/Daf+PK2gEgAvD1qdQsmVKrNS rfOjuIWLl/w7EUXYdk=; b=ssUkjhRizeV8lBCV+KkzaEIGw/5l19fWbJT4MuEn4 ZLsV6mJK+t+Todt/Hb1dWagl3v6Fid+75NeXl1JywVdJ8i65n+eOCaN5Fhrd3K+T mcreg+uAGEtBX55cro0gM0bCxW+6oCIfSzc5M7YRoaf4U6hu5pjVOeOKs+jZaczN 1M= Received: from pb-smtp21.sea.icgroup.com (unknown [127.0.0.1]) by pb-smtp21.pobox.com (Postfix) with ESMTP id 96CCA27BAC; Fri, 15 Dec 2023 15:32:53 -0500 (EST) (envelope-from gitster@pobox.com) Received: from pobox.com (unknown [34.125.193.51]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp21.pobox.com (Postfix) with ESMTPSA id 44DAF27BAB; Fri, 15 Dec 2023 15:32:50 -0500 (EST) (envelope-from gitster@pobox.com) From: Junio C Hamano To: git@vger.kernel.org Cc: Patrick Steinhardt Subject: [PATCH 1/5] git.txt: HEAD is not that special Date: Fri, 15 Dec 2023 12:32:41 -0800 Message-ID: <20231215203245.3622299-2-gitster@pobox.com> X-Mailer: git-send-email 2.43.0-76-g1a87c842ec In-Reply-To: <20231215203245.3622299-1-gitster@pobox.com> References: <20231215203245.3622299-1-gitster@pobox.com> Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Pobox-Relay-ID: 1D81FABA-9B89-11EE-A3D2-A19503B9AAD1-77302942!pb-smtp21.pobox.com The introductory text in "git help git" that describes HEAD called it "a special ref". It is special compared to the more regular refs like refs/heads/master and refs/tags/v1.0.0, but not that special, unlike truly special ones like FETCH_HEAD. Rewrite a few sentences to also introduce the distinction between a regular ref that contain the object name and a symbolic ref that contain the name of another ref. Update the description of HEAD that point at the current branch to use the more correct term, a "symbolic ref". This was found as part of auditing the documentation and in-code comments for uses of "special ref" that refer merely a "pseudo ref". Signed-off-by: Junio C Hamano --- Documentation/git.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Documentation/git.txt b/Documentation/git.txt index 2535a30194..880cdc5d7f 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -1025,10 +1025,11 @@ When first created, objects are stored in individual files, but for efficiency may later be compressed together into "pack files". Named pointers called refs mark interesting points in history. A ref -may contain the SHA-1 name of an object or the name of another ref. Refs -with names beginning `ref/head/` contain the SHA-1 name of the most +may contain the SHA-1 name of an object or the name of another ref (the +latter is called a "symbolic ref"). +Refs with names beginning `ref/head/` contain the SHA-1 name of the most recent commit (or "head") of a branch under development. SHA-1 names of -tags of interest are stored under `ref/tags/`. A special ref named +tags of interest are stored under `ref/tags/`. A symbolic ref named `HEAD` contains the name of the currently checked-out branch. The index file is initialized with a list of all paths and, for each From patchwork Fri Dec 15 20:32:42 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Junio C Hamano X-Patchwork-Id: 13494874 Received: from pb-smtp1.pobox.com (pb-smtp1.pobox.com [64.147.108.70]) (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 8E97447762 for ; Fri, 15 Dec 2023 20:32:55 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=pobox.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pobox.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=pobox.com header.i=@pobox.com header.b="NblPRsAS" Received: from pb-smtp1.pobox.com (unknown [127.0.0.1]) by pb-smtp1.pobox.com (Postfix) with ESMTP id 242981BD36A; Fri, 15 Dec 2023 15:32:54 -0500 (EST) (envelope-from gitster@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to:cc :subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; s=sasl; bh=XsUxuSbFD8r7KwCnbR60MyBkR 6F3NzoekMny3BPgAsA=; b=NblPRsASF4TiYWj7vTLBJzdQwloGlu0AlUdTesW5J abb8RUJTSm92CV6s8dikBpMs+1uMCP7dS1bOyZ8eooU8/uKpKYCsp6aShUXaRb+4 s/KE91A8PgZLqGJnjmY2OriJfJHh6vkdRAu67tRaRGLyO+nqa/x/JE5PDjoEWIJn zA= Received: from pb-smtp1.nyi.icgroup.com (unknown [127.0.0.1]) by pb-smtp1.pobox.com (Postfix) with ESMTP id 1C03F1BD369; Fri, 15 Dec 2023 15:32:54 -0500 (EST) (envelope-from gitster@pobox.com) Received: from pobox.com (unknown [34.125.193.51]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp1.pobox.com (Postfix) with ESMTPSA id 8237F1BD368; Fri, 15 Dec 2023 15:32:53 -0500 (EST) (envelope-from gitster@pobox.com) From: Junio C Hamano To: git@vger.kernel.org Cc: Patrick Steinhardt Subject: [PATCH 2/5] git-bisect.txt: BISECT_HEAD is not that special Date: Fri, 15 Dec 2023 12:32:42 -0800 Message-ID: <20231215203245.3622299-3-gitster@pobox.com> X-Mailer: git-send-email 2.43.0-76-g1a87c842ec In-Reply-To: <20231215203245.3622299-1-gitster@pobox.com> References: <20231215203245.3622299-1-gitster@pobox.com> Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Pobox-Relay-ID: 1F728E66-9B89-11EE-A043-78DCEB2EC81B-77302942!pb-smtp1.pobox.com The description of "git bisect --no-checkout" called BISECT_HEAD a "special ref", but there is nothing special about it. It merely is yet another pseudoref. Signed-off-by: Junio C Hamano --- Documentation/git-bisect.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 191b4a42b6..aa02e46224 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -362,7 +362,7 @@ OPTIONS --no-checkout:: + Do not checkout the new working tree at each iteration of the bisection -process. Instead just update a special reference named `BISECT_HEAD` to make +process. Instead just update the reference named `BISECT_HEAD` to make it point to the commit that should be tested. + This option may be useful when the test you would perform in each step From patchwork Fri Dec 15 20:32:43 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Junio C Hamano X-Patchwork-Id: 13494877 Received: from pb-smtp20.pobox.com (pb-smtp20.pobox.com [173.228.157.52]) (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 918D247F49 for ; Fri, 15 Dec 2023 20:32:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=pobox.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pobox.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=pobox.com header.i=@pobox.com header.b="QfBPR9Jw" Received: from pb-smtp20.pobox.com (unknown [127.0.0.1]) by pb-smtp20.pobox.com (Postfix) with ESMTP id D09DB26EF3; Fri, 15 Dec 2023 15:32:58 -0500 (EST) (envelope-from gitster@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to:cc :subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; s=sasl; bh=l6gssdIBOBnQbWcHAyq63WMEy WqAdSI1lQd40rcK8fc=; b=QfBPR9JwB1jkPVJweGyEywd1+o9XmJI3N4dJXQkuc JHQM3atLiejlFgwFeR6M9PoMFzZRjTo8cGaOf60x7KTYbO0gUrcslzVG2wFkyO+3 Z2jMslvkqO2xm4QWmMy4XWDb19fYfhOA8zh+4y7ee63pSscg6rGD97bq1DASObp+ zM= Received: from pb-smtp20.sea.icgroup.com (unknown [127.0.0.1]) by pb-smtp20.pobox.com (Postfix) with ESMTP id C941F26EF2; Fri, 15 Dec 2023 15:32:58 -0500 (EST) (envelope-from gitster@pobox.com) Received: from pobox.com (unknown [34.125.193.51]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp20.pobox.com (Postfix) with ESMTPSA id 7421F26EF1; Fri, 15 Dec 2023 15:32:55 -0500 (EST) (envelope-from gitster@pobox.com) From: Junio C Hamano To: git@vger.kernel.org Cc: Patrick Steinhardt Subject: [PATCH 3/5] refs.h: HEAD is not that special Date: Fri, 15 Dec 2023 12:32:43 -0800 Message-ID: <20231215203245.3622299-4-gitster@pobox.com> X-Mailer: git-send-email 2.43.0-76-g1a87c842ec In-Reply-To: <20231215203245.3622299-1-gitster@pobox.com> References: <20231215203245.3622299-1-gitster@pobox.com> Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Pobox-Relay-ID: 209A978E-9B89-11EE-9878-F515D2CDFF5E-77302942!pb-smtp20.pobox.com In-code comment explains pseudorefs but used a wrong nomenclature "special ref". Signed-off-by: Junio C Hamano --- refs.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/refs.h b/refs.h index 23211a5ea1..ff113bb12a 100644 --- a/refs.h +++ b/refs.h @@ -56,7 +56,7 @@ struct worktree; * Even with RESOLVE_REF_ALLOW_BAD_NAME, names that escape the refs/ * directory and do not consist of all caps and underscores cannot be * resolved. The function returns NULL for such ref names. - * Caps and underscores refers to the special refs, such as HEAD, + * Caps and underscores refers to the pseudorefs, such as HEAD, * FETCH_HEAD and friends, that all live outside of the refs/ directory. */ #define RESOLVE_REF_READING 0x01 From patchwork Fri Dec 15 20:32:44 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Junio C Hamano X-Patchwork-Id: 13494878 Received: from pb-smtp2.pobox.com (pb-smtp2.pobox.com [64.147.108.71]) (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 EEAB847F5F for ; Fri, 15 Dec 2023 20:33:00 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=pobox.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pobox.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=pobox.com header.i=@pobox.com header.b="ZHajhN49" Received: from pb-smtp2.pobox.com (unknown [127.0.0.1]) by pb-smtp2.pobox.com (Postfix) with ESMTP id 59AFA1BE561; Fri, 15 Dec 2023 15:32:59 -0500 (EST) (envelope-from gitster@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to:cc :subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; s=sasl; bh=9UlA2/3F3fPOPr6wW31fYqZ2k PsB2BGM1n4/34xYdro=; b=ZHajhN49arIkEIsC7oHJoWfhcIyWx74/0Ep7Wl/k+ y7av6ONhZFWAAdeEZYM+jG2838rBpGzlzAzBv7R9+WG46fU0X91cmEY28gU0ZIrr qgDgudzDWazX+zUWwmyX75z/16YJsHRwtdDLyhDgesA98ZWeILG2Or5UqzinbYZM Q0= Received: from pb-smtp2.nyi.icgroup.com (unknown [127.0.0.1]) by pb-smtp2.pobox.com (Postfix) with ESMTP id 501C61BE55F; Fri, 15 Dec 2023 15:32:59 -0500 (EST) (envelope-from gitster@pobox.com) Received: from pobox.com (unknown [34.125.193.51]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp2.pobox.com (Postfix) with ESMTPSA id B13181BE55E; Fri, 15 Dec 2023 15:32:58 -0500 (EST) (envelope-from gitster@pobox.com) From: Junio C Hamano To: git@vger.kernel.org Cc: Patrick Steinhardt Subject: [PATCH 4/5] docs: AUTO_MERGE is not that special Date: Fri, 15 Dec 2023 12:32:44 -0800 Message-ID: <20231215203245.3622299-5-gitster@pobox.com> X-Mailer: git-send-email 2.43.0-76-g1a87c842ec In-Reply-To: <20231215203245.3622299-1-gitster@pobox.com> References: <20231215203245.3622299-1-gitster@pobox.com> Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Pobox-Relay-ID: 228BB226-9B89-11EE-A475-25B3960A682E-77302942!pb-smtp2.pobox.com A handful of manual pages called AUTO_MERGE a "special ref", but there is nothing special about it. It merely is yet another pseudoref. Signed-off-by: Junio C Hamano --- Documentation/git-diff.txt | 2 +- Documentation/git-merge.txt | 2 +- Documentation/user-manual.txt | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 08087ffad5..c065f023ec 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -103,7 +103,7 @@ Just in case you are doing something exotic, it should be noted that all of the in the above description, except in the `--merge-base` case and in the last two forms that use `..` notations, can be any . A tree of interest is the one pointed to -by the special ref `AUTO_MERGE`, which is written by the 'ort' merge +by the ref named `AUTO_MERGE`, which is written by the 'ort' merge strategy upon hitting merge conflicts (see linkgit:git-merge[1]). Comparing the working tree with `AUTO_MERGE` shows changes you've made so far to resolve textual conflicts (see the examples below). diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index e8ab340319..3e9557a44b 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -196,7 +196,7 @@ happens: can inspect the stages with `git ls-files -u`). The working tree files contain the result of the merge operation; i.e. 3-way merge results with familiar conflict markers `<<<` `===` `>>>`. -5. A special ref `AUTO_MERGE` is written, pointing to a tree +5. A ref named `AUTO_MERGE` is written, pointing to a tree corresponding to the current content of the working tree (including conflict markers for textual conflicts). Note that this ref is only written when the 'ort' merge strategy is used (the default). diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index d8dbe6b56d..5d32ff2384 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1344,7 +1344,7 @@ $ git diff --theirs file.txt # same as the above. ------------------------------------------------- When using the 'ort' merge strategy (the default), before updating the working -tree with the result of the merge, Git writes a special ref named AUTO_MERGE +tree with the result of the merge, Git writes a ref named AUTO_MERGE reflecting the state of the tree it is about to write. Conflicted paths with textual conflicts that could not be automatically merged are written to this tree with conflict markers, just as in the working tree. AUTO_MERGE can thus be From patchwork Fri Dec 15 20:32:45 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Junio C Hamano X-Patchwork-Id: 13494879 Received: from pb-smtp21.pobox.com (pb-smtp21.pobox.com [173.228.157.53]) (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 77ACE482EC for ; Fri, 15 Dec 2023 20:33:04 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=pobox.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pobox.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=pobox.com header.i=@pobox.com header.b="aGolkbC1" Received: from pb-smtp21.pobox.com (unknown [127.0.0.1]) by pb-smtp21.pobox.com (Postfix) with ESMTP id 018CA27BB2; Fri, 15 Dec 2023 15:33:04 -0500 (EST) (envelope-from gitster@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to:cc :subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; s=sasl; bh=8uzN5/GO8OTRPgT7KPwlxPD/w UXVwZ8lS1vq9fTGu1A=; b=aGolkbC1knrmHD4bi3P/uGlTq8L69vwYFNeXB/INN 8L143+ij/xT/QZ7lp1BLK7l0skijL9entr01V78txdSTlNTp4p3itlnETv/GKW/X Qs/qUrPxrCP/nfH8DFrZYpcVYKBB4bXvbpNu5Cu/t7A5d28NB56eoF8LF5qyHc8L 3U= Received: from pb-smtp21.sea.icgroup.com (unknown [127.0.0.1]) by pb-smtp21.pobox.com (Postfix) with ESMTP id EEA4727BB1; Fri, 15 Dec 2023 15:33:03 -0500 (EST) (envelope-from gitster@pobox.com) Received: from pobox.com (unknown [34.125.193.51]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp21.pobox.com (Postfix) with ESMTPSA id 9E9BD27BAE; Fri, 15 Dec 2023 15:33:00 -0500 (EST) (envelope-from gitster@pobox.com) From: Junio C Hamano To: git@vger.kernel.org Cc: Patrick Steinhardt Subject: [PATCH 5/5] docs: MERGE_AUTOSTASH is not that special Date: Fri, 15 Dec 2023 12:32:45 -0800 Message-ID: <20231215203245.3622299-6-gitster@pobox.com> X-Mailer: git-send-email 2.43.0-76-g1a87c842ec In-Reply-To: <20231215203245.3622299-1-gitster@pobox.com> References: <20231215203245.3622299-1-gitster@pobox.com> Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Pobox-Relay-ID: 23B0CB8C-9B89-11EE-878F-A19503B9AAD1-77302942!pb-smtp21.pobox.com A handful of manual pages called MERGE_AUTOSTASH a "special ref", but there is nothing special about it. It merely is yet another pseudoref. Signed-off-by: Junio C Hamano --- Documentation/merge-options.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index d8f7cd7ca0..3eaefc4e94 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -191,7 +191,7 @@ endif::git-pull[] --autostash:: --no-autostash:: Automatically create a temporary stash entry before the operation - begins, record it in the special ref `MERGE_AUTOSTASH` + begins, record it in the ref `MERGE_AUTOSTASH` and apply it after the operation ends. This means that you can run the operation on a dirty worktree. However, use with care: the final stash application after a successful