{"thread":{"id":"61242","subject":"[PATCH 0/2] improve documentation around git-update-ref","startedAt":"2024-04-01T14:45:48Z","lastAt":"2024-04-02T06:56:42Z","messageCount":11,"participants":["Karthik Nayak","Junio C Hamano","Patrick Steinhardt"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"491960","messageId":"20240401144542.88027-1-knayak@gitlab.com","threadId":"61242","inReplyTo":null,"subject":"[PATCH 0/2] improve documentation around git-update-ref","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-04-01T14:45:40Z","receivedAt":"2024-04-01T14:45:48Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"From: Karthik Nayak <karthik.188@gmail.com>\n\nThis patch series was derived out of the discussion [1] around my other\npatch series to add symref support for `git-update-ref(1)` [2].\n\nThe aim of these patches is to improve clarity around OIDs in the\ndocumentation. This makes it easier to draw parallels between regular\nref updates and symref updates. The symref patch series will be rebased\non top of this in the upcoming version.\n\n[1]: https://public-inbox.org/git/20240330224623.579457-1-knayak@gitlab.com/T/#m7bb4d1f44b656d7cfb73ed3220b990aa6d1ac247\n[2]: https://public-inbox.org/git/20240330224623.579457-1-knayak@gitlab.com/T/#t\n\nKarthik Nayak (2):\n  update-ref: use {old,new}-oid instead of {old,new}value\n  githooks: use {old,new}-oid instead of {old,new}-value\n\n Documentation/git-update-ref.txt | 58 ++++++++++++++++----------------\n Documentation/githooks.txt       | 16 ++++-----\n builtin/update-ref.c             | 26 +++++++-------\n 3 files changed, 50 insertions(+), 50 deletions(-)\n\n-- \n2.43.GIT\n\n"},{"id":"491961","messageId":"20240401144542.88027-2-knayak@gitlab.com","threadId":"61242","inReplyTo":"20240401144542.88027-1-knayak@gitlab.com","subject":"[PATCH 1/2] update-ref: use {old,new}-oid instead of {old,new}value","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-04-01T14:45:41Z","receivedAt":"2024-04-01T14:45:52Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"From: Karthik Nayak <karthik.188@gmail.com>\n\nThe `git-update-ref` command is used to modify references. The usage of\n{old,new}value in the documentation refers to the OIDs. This is fine\nsince the command only works with regular references which hold OIDs.\nBut if the command is updated to support symrefs, we'd also be dealing\nwith {old,new}-refs.\n\nTo improve clarity around what exactly {old,new}value mean, let's rename\nit to {old,new}-oid.\n\nSigned-off-by: Karthik Nayak <karthik.188@gmail.com>\n---\n Documentation/git-update-ref.txt | 58 ++++++++++++++++----------------\n builtin/update-ref.c             | 26 +++++++-------\n 2 files changed, 42 insertions(+), 42 deletions(-)\n\ndiff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt\nindex 0561808cca..374a2ebd2b 100644\n--- a/Documentation/git-update-ref.txt\n+++ b/Documentation/git-update-ref.txt\n@@ -8,21 +8,21 @@ git-update-ref - Update the object name stored in a ref safely\n SYNOPSIS\n --------\n [verse]\n-'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<oldvalue>] | [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z])\n+'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<old-oid>] | [--create-reflog] <ref> <new-oid> [<old-oid>] | --stdin [-z])\n \n DESCRIPTION\n -----------\n-Given two arguments, stores the <newvalue> in the <ref>, possibly\n+Given two arguments, stores the <new-oid> in the <ref>, possibly\n dereferencing the symbolic refs.  E.g. `git update-ref HEAD\n-<newvalue>` updates the current branch head to the new object.\n+<new-oid>` updates the current branch head to the new object.\n \n-Given three arguments, stores the <newvalue> in the <ref>,\n+Given three arguments, stores the <new-oid> in the <ref>,\n possibly dereferencing the symbolic refs, after verifying that\n-the current value of the <ref> matches <oldvalue>.\n-E.g. `git update-ref refs/heads/master <newvalue> <oldvalue>`\n-updates the master branch head to <newvalue> only if its current\n-value is <oldvalue>.  You can specify 40 \"0\" or an empty string\n-as <oldvalue> to make sure that the ref you are creating does\n+the current value of the <ref> matches <old-oid>.\n+E.g. `git update-ref refs/heads/master <new-oid> <old-oid>`\n+updates the master branch head to <new-oid> only if its current\n+value is <old-oid>.  You can specify 40 \"0\" or an empty string\n+as <old-oid> to make sure that the ref you are creating does\n not exist.\n \n It also allows a \"ref\" file to be a symbolic pointer to another\n@@ -56,15 +56,15 @@ ref symlink to some other tree, if you have copied a whole\n archive by creating a symlink tree).\n \n With `-d` flag, it deletes the named <ref> after verifying it\n-still contains <oldvalue>.\n+still contains <old-oid>.\n \n With `--stdin`, update-ref reads instructions from standard input and\n performs all modifications together.  Specify commands of the form:\n \n-\tupdate SP <ref> SP <newvalue> [SP <oldvalue>] LF\n-\tcreate SP <ref> SP <newvalue> LF\n-\tdelete SP <ref> [SP <oldvalue>] LF\n-\tverify SP <ref> [SP <oldvalue>] LF\n+\tupdate SP <ref> SP <new-oid> [SP <old-oid>] LF\n+\tcreate SP <ref> SP <new-oid> LF\n+\tdelete SP <ref> [SP <old-oid>] LF\n+\tverify SP <ref> [SP <old-oid>] LF\n \toption SP <opt> LF\n \tstart LF\n \tprepare LF\n@@ -82,10 +82,10 @@ specify a missing value, omit the value and its preceding SP entirely.\n Alternatively, use `-z` to specify in NUL-terminated format, without\n quoting:\n \n-\tupdate SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL\n-\tcreate SP <ref> NUL <newvalue> NUL\n-\tdelete SP <ref> NUL [<oldvalue>] NUL\n-\tverify SP <ref> NUL [<oldvalue>] NUL\n+\tupdate SP <ref> NUL <new-oid> NUL [<old-oid>] NUL\n+\tcreate SP <ref> NUL <new-oid> NUL\n+\tdelete SP <ref> NUL [<old-oid>] NUL\n+\tverify SP <ref> NUL [<old-oid>] NUL\n \toption SP <opt> NUL\n \tstart NUL\n \tprepare NUL\n@@ -100,22 +100,22 @@ recognizes as an object name.  Commands in any other format or a\n repeated <ref> produce an error.  Command meanings are:\n \n update::\n-\tSet <ref> to <newvalue> after verifying <oldvalue>, if given.\n-\tSpecify a zero <newvalue> to ensure the ref does not exist\n-\tafter the update and/or a zero <oldvalue> to make sure the\n+\tSet <ref> to <new-oid> after verifying <old-oid>, if given.\n+\tSpecify a zero <new-oid> to ensure the ref does not exist\n+\tafter the update and/or a zero <old-oid> to make sure the\n \tref does not exist before the update.\n \n create::\n-\tCreate <ref> with <newvalue> after verifying it does not\n-\texist.  The given <newvalue> may not be zero.\n+\tCreate <ref> with <new-oid> after verifying it does not\n+\texist.  The given <new-oid> may not be zero.\n \n delete::\n-\tDelete <ref> after verifying it exists with <oldvalue>, if\n-\tgiven.  If given, <oldvalue> may not be zero.\n+\tDelete <ref> after verifying it exists with <old-oid>, if\n+\tgiven.  If given, <old-oid> may not be zero.\n \n verify::\n-\tVerify <ref> against <oldvalue> but do not change it.  If\n-\t<oldvalue> is zero or missing, the ref must not exist.\n+\tVerify <ref> against <old-oid> but do not change it.  If\n+\t<old-oid> is zero or missing, the ref must not exist.\n \n option::\n \tModify the behavior of the next command naming a <ref>.\n@@ -141,7 +141,7 @@ abort::\n \tAbort the transaction, releasing all locks if the transaction is in\n \tprepared state.\n \n-If all <ref>s can be locked with matching <oldvalue>s\n+If all <ref>s can be locked with matching <old-oid>s\n simultaneously, all modifications are performed.  Otherwise, no\n modifications are performed.  Note that while each individual\n <ref> is updated or deleted atomically, a concurrent reader may\n@@ -161,7 +161,7 @@ formatted as:\n \n Where \"oldsha1\" is the 40 character hexadecimal value previously\n stored in <ref>, \"newsha1\" is the 40 character hexadecimal value of\n-<newvalue> and \"committer\" is the committer's name, email address\n+<new-oid> and \"committer\" is the committer's name, email address\n and date in the standard Git committer ident format.\n \n Optionally with -m:\ndiff --git a/builtin/update-ref.c b/builtin/update-ref.c\nindex 61338a01ec..e46afbc46d 100644\n--- a/builtin/update-ref.c\n+++ b/builtin/update-ref.c\n@@ -9,8 +9,8 @@\n #include \"repository.h\"\n \n static const char * const git_update_ref_usage[] = {\n-\tN_(\"git update-ref [<options>] -d <refname> [<old-val>]\"),\n-\tN_(\"git update-ref [<options>]    <refname> <new-val> [<old-val>]\"),\n+\tN_(\"git update-ref [<options>] -d <refname> [<old-oid>]\"),\n+\tN_(\"git update-ref [<options>]    <refname> <new-oid> [<old-oid>]\"),\n \tN_(\"git update-ref [<options>] --stdin [-z]\"),\n \tNULL\n };\n@@ -77,14 +77,14 @@ static char *parse_refname(const char **next)\n }\n \n /*\n- * The value being parsed is <oldvalue> (as opposed to <newvalue>; the\n+ * The value being parsed is <old-oid> (as opposed to <new-oid>; the\n  * difference affects which error messages are generated):\n  */\n #define PARSE_SHA1_OLD 0x01\n \n /*\n  * For backwards compatibility, accept an empty string for update's\n- * <newvalue> in binary mode to be equivalent to specifying zeros.\n+ * <new-oid> in binary mode to be equivalent to specifying zeros.\n  */\n #define PARSE_SHA1_ALLOW_EMPTY 0x02\n \n@@ -140,7 +140,7 @@ static int parse_next_oid(const char **next, const char *end,\n \t\t\t\tgoto invalid;\n \t\t} else if (flags & PARSE_SHA1_ALLOW_EMPTY) {\n \t\t\t/* With -z, treat an empty value as all zeros: */\n-\t\t\twarning(\"%s %s: missing <newvalue>, treating as zero\",\n+\t\t\twarning(\"%s %s: missing <new-oid>, treating as zero\",\n \t\t\t\tcommand, refname);\n \t\t\toidclr(oid);\n \t\t} else {\n@@ -158,14 +158,14 @@ static int parse_next_oid(const char **next, const char *end,\n \n  invalid:\n \tdie(flags & PARSE_SHA1_OLD ?\n-\t    \"%s %s: invalid <oldvalue>: %s\" :\n-\t    \"%s %s: invalid <newvalue>: %s\",\n+\t    \"%s %s: invalid <old-oid>: %s\" :\n+\t    \"%s %s: invalid <new-oid>: %s\",\n \t    command, refname, arg.buf);\n \n  eof:\n \tdie(flags & PARSE_SHA1_OLD ?\n-\t    \"%s %s: unexpected end of input when reading <oldvalue>\" :\n-\t    \"%s %s: unexpected end of input when reading <newvalue>\",\n+\t    \"%s %s: unexpected end of input when reading <old-oid>\" :\n+\t    \"%s %s: unexpected end of input when reading <new-oid>\",\n \t    command, refname);\n }\n \n@@ -194,7 +194,7 @@ static void parse_cmd_update(struct ref_transaction *transaction,\n \n \tif (parse_next_oid(&next, end, &new_oid, \"update\", refname,\n \t\t\t   PARSE_SHA1_ALLOW_EMPTY))\n-\t\tdie(\"update %s: missing <newvalue>\", refname);\n+\t\tdie(\"update %s: missing <new-oid>\", refname);\n \n \thave_old = !parse_next_oid(&next, end, &old_oid, \"update\", refname,\n \t\t\t\t   PARSE_SHA1_OLD);\n@@ -225,10 +225,10 @@ static void parse_cmd_create(struct ref_transaction *transaction,\n \t\tdie(\"create: missing <ref>\");\n \n \tif (parse_next_oid(&next, end, &new_oid, \"create\", refname, 0))\n-\t\tdie(\"create %s: missing <newvalue>\", refname);\n+\t\tdie(\"create %s: missing <new-oid>\", refname);\n \n \tif (is_null_oid(&new_oid))\n-\t\tdie(\"create %s: zero <newvalue>\", refname);\n+\t\tdie(\"create %s: zero <new-oid>\", refname);\n \n \tif (*next != line_termination)\n \t\tdie(\"create %s: extra input: %s\", refname, next);\n@@ -260,7 +260,7 @@ static void parse_cmd_delete(struct ref_transaction *transaction,\n \t\thave_old = 0;\n \t} else {\n \t\tif (is_null_oid(&old_oid))\n-\t\t\tdie(\"delete %s: zero <oldvalue>\", refname);\n+\t\t\tdie(\"delete %s: zero <old-oid>\", refname);\n \t\thave_old = 1;\n \t}\n \n-- \n2.43.GIT\n\n"},{"id":"491962","messageId":"20240401144542.88027-3-knayak@gitlab.com","threadId":"61242","inReplyTo":"20240401144542.88027-1-knayak@gitlab.com","subject":"[PATCH 2/2] githooks: use {old,new}-oid instead of {old,new}-value","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-04-01T14:45:42Z","receivedAt":"2024-04-01T14:45:54Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"From: Karthik Nayak <karthik.188@gmail.com>\n\nSimilar to the previous commit, rename {old,new}-value in the 'githooks'\ndocumentation to {old,new}-oid. This improves clarity and also ensures\nconsistency within the document.\n\nSigned-off-by: Karthik Nayak <karthik.188@gmail.com>\n---\n Documentation/githooks.txt | 16 ++++++++--------\n 1 file changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/githooks.txt b/Documentation/githooks.txt\nindex 37f91d5b50..ee9b92c90d 100644\n--- a/Documentation/githooks.txt\n+++ b/Documentation/githooks.txt\n@@ -275,12 +275,12 @@ This hook executes once for the receive operation. It takes no\n arguments, but for each ref to be updated it receives on standard\n input a line of the format:\n \n-  <old-value> SP <new-value> SP <ref-name> LF\n+  <old-oid> SP <new-oid> SP <ref-name> LF\n \n-where `<old-value>` is the old object name stored in the ref,\n-`<new-value>` is the new object name to be stored in the ref and\n+where `<old-oid>` is the old object name stored in the ref,\n+`<new-oid>` is the new object name to be stored in the ref and\n `<ref-name>` is the full name of the ref.\n-When creating a new ref, `<old-value>` is the all-zeroes object name.\n+When creating a new ref, `<old-oid>` is the all-zeroes object name.\n \n If the hook exits with non-zero status, none of the refs will be\n updated. If the hook exits with zero, updating of individual refs can\n@@ -503,13 +503,13 @@ given reference transaction is in:\n For each reference update that was added to the transaction, the hook\n receives on standard input a line of the format:\n \n-  <old-value> SP <new-value> SP <ref-name> LF\n+  <old-oid> SP <new-oid> SP <ref-name> LF\n \n-where `<old-value>` is the old object name passed into the reference\n-transaction, `<new-value>` is the new object name to be stored in the\n+where `<old-oid>` is the old object name passed into the reference\n+transaction, `<new-oid>` is the new object name to be stored in the\n ref and `<ref-name>` is the full name of the ref. When force updating\n the reference regardless of its current value or when the reference is\n-to be created anew, `<old-value>` is the all-zeroes object name. To\n+to be created anew, `<old-oid>` is the all-zeroes object name. To\n distinguish these cases, you can inspect the current value of\n `<ref-name>` via `git rev-parse`.\n \n-- \n2.43.GIT\n\n"},{"id":"491984","messageId":"xmqqo7as957h.fsf@gitster.g","threadId":"61242","inReplyTo":"20240401144542.88027-2-knayak@gitlab.com","subject":"Re: [PATCH 1/2] update-ref: use {old,new}-oid instead of {old,new}value","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-04-01T20:51:46Z","receivedAt":"2024-04-01T20:51:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Karthik Nayak <karthik.188@gmail.com> writes:\n\n> From: Karthik Nayak <karthik.188@gmail.com>\n>\n> The `git-update-ref` command is used to modify references. The usage of\n> {old,new}value in the documentation refers to the OIDs. This is fine\n> since the command only works with regular references which hold OIDs.\n> But if the command is updated to support symrefs, we'd also be dealing\n> with {old,new}-refs.\n>\n> To improve clarity around what exactly {old,new}value mean, let's rename\n> it to {old,new}-oid.\n>\n> Signed-off-by: Karthik Nayak <karthik.188@gmail.com>\n> ---\n>  Documentation/git-update-ref.txt | 58 ++++++++++++++++----------------\n>  builtin/update-ref.c             | 26 +++++++-------\n>  2 files changed, 42 insertions(+), 42 deletions(-)\n\nDid you run t1400 after this update?  There may be other tests that\nthe message update is breaking but that was the first one I noticed.\n"},{"id":"492002","messageId":"CAOLa=ZQRw1Cu9rcKYoxzsL8V3LWjyMKuOkcutzqRJb+cpyBNTA@mail.gmail.com","threadId":"61242","inReplyTo":"xmqqo7as957h.fsf@gitster.g","subject":"Re: [PATCH 1/2] update-ref: use {old,new}-oid instead of {old,new}value","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-04-01T22:38:52Z","receivedAt":"2024-04-01T22:38:55Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Karthik Nayak <karthik.188@gmail.com> writes:\n>\n>> From: Karthik Nayak <karthik.188@gmail.com>\n>>\n>> The `git-update-ref` command is used to modify references. The usage of\n>> {old,new}value in the documentation refers to the OIDs. This is fine\n>> since the command only works with regular references which hold OIDs.\n>> But if the command is updated to support symrefs, we'd also be dealing\n>> with {old,new}-refs.\n>>\n>> To improve clarity around what exactly {old,new}value mean, let's rename\n>> it to {old,new}-oid.\n>>\n>> Signed-off-by: Karthik Nayak <karthik.188@gmail.com>\n>> ---\n>>  Documentation/git-update-ref.txt | 58 ++++++++++++++++----------------\n>>  builtin/update-ref.c             | 26 +++++++-------\n>>  2 files changed, 42 insertions(+), 42 deletions(-)\n>\n> Did you run t1400 after this update?  There may be other tests that\n> the message update is breaking but that was the first one I noticed.\n\nI definitely didn't. It totally slipped my mind, I was thinking that I\nonly modified the *.txt files. I will send in a new version after\nensuring all tests are fixed.\n"},{"id":"492003","messageId":"xmqqr0fo7kop.fsf@gitster.g","threadId":"61242","inReplyTo":"CAOLa=ZQRw1Cu9rcKYoxzsL8V3LWjyMKuOkcutzqRJb+cpyBNTA@mail.gmail.com","subject":"Re: [PATCH 1/2] update-ref: use {old,new}-oid instead of {old,new}value","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-04-01T23:00:22Z","receivedAt":"2024-04-01T23:00:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Karthik Nayak <karthik.188@gmail.com> writes:\n\n>> Did you run t1400 after this update?  There may be other tests that\n>> the message update is breaking but that was the first one I noticed.\n>\n> I definitely didn't. It totally slipped my mind, I was thinking that I\n> only modified the *.txt files. I will send in a new version after\n> ensuring all tests are fixed.\n\nHere is what I have.\n\nSubject: [PATCH] fixup! update-ref: use {old,new}-oid instead of {old,new}value\n\n---\n t/t1400-update-ref.sh | 34 +++++++++++++++++-----------------\n 1 file changed, 17 insertions(+), 17 deletions(-)\n\ndiff --git a/t/t1400-update-ref.sh b/t/t1400-update-ref.sh\nindex 6ebc3ef945..d59ee1ab4a 100755\n--- a/t/t1400-update-ref.sh\n+++ b/t/t1400-update-ref.sh\n@@ -622,7 +622,7 @@ test_expect_success 'stdin fails create with no ref' '\n test_expect_success 'stdin fails create with no new value' '\n \techo \"create $a\" >stdin &&\n \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n-\tgrep \"fatal: create $a: missing <newvalue>\" err\n+\tgrep \"fatal: create $a: missing <new-oid>\" err\n '\n \n test_expect_success 'stdin fails create with too many arguments' '\n@@ -640,7 +640,7 @@ test_expect_success 'stdin fails update with no ref' '\n test_expect_success 'stdin fails update with no new value' '\n \techo \"update $a\" >stdin &&\n \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n-\tgrep \"fatal: update $a: missing <newvalue>\" err\n+\tgrep \"fatal: update $a: missing <new-oid>\" err\n '\n \n test_expect_success 'stdin fails update with too many arguments' '\n@@ -765,21 +765,21 @@ test_expect_success 'stdin update ref fails with wrong old value' '\n test_expect_success 'stdin update ref fails with bad old value' '\n \techo \"update $c $m does-not-exist\" >stdin &&\n \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n-\tgrep \"fatal: update $c: invalid <oldvalue>: does-not-exist\" err &&\n+\tgrep \"fatal: update $c: invalid <old-oid>: does-not-exist\" err &&\n \ttest_must_fail git rev-parse --verify -q $c\n '\n \n test_expect_success 'stdin create ref fails with bad new value' '\n \techo \"create $c does-not-exist\" >stdin &&\n \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n-\tgrep \"fatal: create $c: invalid <newvalue>: does-not-exist\" err &&\n+\tgrep \"fatal: create $c: invalid <new-oid>: does-not-exist\" err &&\n \ttest_must_fail git rev-parse --verify -q $c\n '\n \n test_expect_success 'stdin create ref fails with zero new value' '\n \techo \"create $c \" >stdin &&\n \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n-\tgrep \"fatal: create $c: zero <newvalue>\" err &&\n+\tgrep \"fatal: create $c: zero <new-oid\" err &&\n \ttest_must_fail git rev-parse --verify -q $c\n '\n \n@@ -803,7 +803,7 @@ test_expect_success 'stdin delete ref fails with wrong old value' '\n test_expect_success 'stdin delete ref fails with zero old value' '\n \techo \"delete $a \" >stdin &&\n \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n-\tgrep \"fatal: delete $a: zero <oldvalue>\" err &&\n+\tgrep \"fatal: delete $a: zero <old-oid>\" err &&\n \tgit rev-parse $m >expect &&\n \tgit rev-parse $a >actual &&\n \ttest_cmp expect actual\n@@ -1027,7 +1027,7 @@ test_expect_success 'stdin -z fails create with no ref' '\n test_expect_success 'stdin -z fails create with no new value' '\n \tprintf $F \"create $a\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: create $a: unexpected end of input when reading <newvalue>\" err\n+\tgrep \"fatal: create $a: unexpected end of input when reading <new-oid>\" err\n '\n \n test_expect_success 'stdin -z fails create with too many arguments' '\n@@ -1045,27 +1045,27 @@ test_expect_success 'stdin -z fails update with no ref' '\n test_expect_success 'stdin -z fails update with too few args' '\n \tprintf $F \"update $a\" \"$m\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: update $a: unexpected end of input when reading <oldvalue>\" err\n+\tgrep \"fatal: update $a: unexpected end of input when reading <old-oid>\" err\n '\n \n test_expect_success 'stdin -z emits warning with empty new value' '\n \tgit update-ref $a $m &&\n \tprintf $F \"update $a\" \"\" \"\" >stdin &&\n \tgit update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"warning: update $a: missing <newvalue>, treating as zero\" err &&\n+\tgrep \"warning: update $a: missing <new-oid>, treating as zero\" err &&\n \ttest_must_fail git rev-parse --verify -q $a\n '\n \n test_expect_success 'stdin -z fails update with no new value' '\n \tprintf $F \"update $a\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: update $a: unexpected end of input when reading <newvalue>\" err\n+\tgrep \"fatal: update $a: unexpected end of input when reading <new-oid>\" err\n '\n \n test_expect_success 'stdin -z fails update with no old value' '\n \tprintf $F \"update $a\" \"$m\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: update $a: unexpected end of input when reading <oldvalue>\" err\n+\tgrep \"fatal: update $a: unexpected end of input when reading <old-oid>\" err\n '\n \n test_expect_success 'stdin -z fails update with too many arguments' '\n@@ -1083,7 +1083,7 @@ test_expect_success 'stdin -z fails delete with no ref' '\n test_expect_success 'stdin -z fails delete with no old value' '\n \tprintf $F \"delete $a\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: delete $a: unexpected end of input when reading <oldvalue>\" err\n+\tgrep \"fatal: delete $a: unexpected end of input when reading <old-oid>\" err\n '\n \n test_expect_success 'stdin -z fails delete with too many arguments' '\n@@ -1101,7 +1101,7 @@ test_expect_success 'stdin -z fails verify with too many arguments' '\n test_expect_success 'stdin -z fails verify with no old value' '\n \tprintf $F \"verify $a\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: verify $a: unexpected end of input when reading <oldvalue>\" err\n+\tgrep \"fatal: verify $a: unexpected end of input when reading <old-oid>\" err\n '\n \n test_expect_success 'stdin -z fails option with unknown name' '\n@@ -1160,7 +1160,7 @@ test_expect_success 'stdin -z update ref fails with wrong old value' '\n test_expect_success 'stdin -z update ref fails with bad old value' '\n \tprintf $F \"update $c\" \"$m\" \"does-not-exist\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: update $c: invalid <oldvalue>: does-not-exist\" err &&\n+\tgrep \"fatal: update $c: invalid <old-oid>: does-not-exist\" err &&\n \ttest_must_fail git rev-parse --verify -q $c\n '\n \n@@ -1178,14 +1178,14 @@ test_expect_success 'stdin -z create ref fails with bad new value' '\n \tgit update-ref -d \"$c\" &&\n \tprintf $F \"create $c\" \"does-not-exist\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: create $c: invalid <newvalue>: does-not-exist\" err &&\n+\tgrep \"fatal: create $c: invalid <new-oid>: does-not-exist\" err &&\n \ttest_must_fail git rev-parse --verify -q $c\n '\n \n test_expect_success 'stdin -z create ref fails with empty new value' '\n \tprintf $F \"create $c\" \"\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: create $c: missing <newvalue>\" err &&\n+\tgrep \"fatal: create $c: missing <new-oid>\" err &&\n \ttest_must_fail git rev-parse --verify -q $c\n '\n \n@@ -1209,7 +1209,7 @@ test_expect_success 'stdin -z delete ref fails with wrong old value' '\n test_expect_success 'stdin -z delete ref fails with zero old value' '\n \tprintf $F \"delete $a\" \"$Z\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: delete $a: zero <oldvalue>\" err &&\n+\tgrep \"fatal: delete $a: zero <old-oid>\" err &&\n \tgit rev-parse $m >expect &&\n \tgit rev-parse $a >actual &&\n \ttest_cmp expect actual\n-- \n2.44.0-448-gc2cbfbd2e2\n\n"},{"id":"492020","messageId":"20240402064915.191104-1-knayak@gitlab.com","threadId":"61242","inReplyTo":"20240401144542.88027-1-knayak@gitlab.com","subject":"[PATCH v2 0/2] improve documentation around git-update-ref","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-04-02T06:49:13Z","receivedAt":"2024-04-02T06:49:21Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"From: Karthik Nayak <karthik.188@gmail.com>\n\nThis patch series was derived out of the discussion [1] around my other\npatch series to add symref support for `git-update-ref(1)` [2].\n\nThe aim of these patches is to improve clarity around OIDs in the\ndocumentation. This makes it easier to draw parallels between regular\nref updates and symref updates. The symref patch series will be rebased\non top of this in the upcoming version.\n\nChanges in v2:\n- Fixed broken tests due to changes in update-ref.c\n\nRange diff against v1:\n1:  5a315a0aa0 ! 1:  f5cc3738ee update-ref: use {old,new}-oid instead of {old,new}value\n    @@ builtin/update-ref.c: static void parse_cmd_delete(struct ref_transaction *trans\n      \t\thave_old = 1;\n      \t}\n      \n    +\n    + ## t/t1400-update-ref.sh ##\n    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin fails create with no ref' '\n    + test_expect_success 'stdin fails create with no new value' '\n    + \techo \"create $a\" >stdin &&\n    + \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: create $a: missing <newvalue>\" err\n    ++\tgrep \"fatal: create $a: missing <new-oid>\" err\n    + '\n    + \n    + test_expect_success 'stdin fails create with too many arguments' '\n    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin fails update with no ref' '\n    + test_expect_success 'stdin fails update with no new value' '\n    + \techo \"update $a\" >stdin &&\n    + \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: update $a: missing <newvalue>\" err\n    ++\tgrep \"fatal: update $a: missing <new-oid>\" err\n    + '\n    + \n    + test_expect_success 'stdin fails update with too many arguments' '\n    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin update ref fails with wrong old value' '\n    + test_expect_success 'stdin update ref fails with bad old value' '\n    + \techo \"update $c $m does-not-exist\" >stdin &&\n    + \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: update $c: invalid <oldvalue>: does-not-exist\" err &&\n    ++\tgrep \"fatal: update $c: invalid <old-oid>: does-not-exist\" err &&\n    + \ttest_must_fail git rev-parse --verify -q $c\n    + '\n    + \n    + test_expect_success 'stdin create ref fails with bad new value' '\n    + \techo \"create $c does-not-exist\" >stdin &&\n    + \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: create $c: invalid <newvalue>: does-not-exist\" err &&\n    ++\tgrep \"fatal: create $c: invalid <new-oid>: does-not-exist\" err &&\n    + \ttest_must_fail git rev-parse --verify -q $c\n    + '\n    + \n    + test_expect_success 'stdin create ref fails with zero new value' '\n    + \techo \"create $c \" >stdin &&\n    + \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: create $c: zero <newvalue>\" err &&\n    ++\tgrep \"fatal: create $c: zero <new-oid>\" err &&\n    + \ttest_must_fail git rev-parse --verify -q $c\n    + '\n    + \n    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin delete ref fails with wrong old value' '\n    + test_expect_success 'stdin delete ref fails with zero old value' '\n    + \techo \"delete $a \" >stdin &&\n    + \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: delete $a: zero <oldvalue>\" err &&\n    ++\tgrep \"fatal: delete $a: zero <old-oid>\" err &&\n    + \tgit rev-parse $m >expect &&\n    + \tgit rev-parse $a >actual &&\n    + \ttest_cmp expect actual\n    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z fails create with no ref' '\n    + test_expect_success 'stdin -z fails create with no new value' '\n    + \tprintf $F \"create $a\" >stdin &&\n    + \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: create $a: unexpected end of input when reading <newvalue>\" err\n    ++\tgrep \"fatal: create $a: unexpected end of input when reading <new-oid>\" err\n    + '\n    + \n    + test_expect_success 'stdin -z fails create with too many arguments' '\n    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z fails update with no ref' '\n    + test_expect_success 'stdin -z fails update with too few args' '\n    + \tprintf $F \"update $a\" \"$m\" >stdin &&\n    + \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: update $a: unexpected end of input when reading <oldvalue>\" err\n    ++\tgrep \"fatal: update $a: unexpected end of input when reading <old-oid>\" err\n    + '\n    + \n    + test_expect_success 'stdin -z emits warning with empty new value' '\n    + \tgit update-ref $a $m &&\n    + \tprintf $F \"update $a\" \"\" \"\" >stdin &&\n    + \tgit update-ref -z --stdin <stdin 2>err &&\n    +-\tgrep \"warning: update $a: missing <newvalue>, treating as zero\" err &&\n    ++\tgrep \"warning: update $a: missing <new-oid>, treating as zero\" err &&\n    + \ttest_must_fail git rev-parse --verify -q $a\n    + '\n    + \n    + test_expect_success 'stdin -z fails update with no new value' '\n    + \tprintf $F \"update $a\" >stdin &&\n    + \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: update $a: unexpected end of input when reading <newvalue>\" err\n    ++\tgrep \"fatal: update $a: unexpected end of input when reading <new-oid>\" err\n    + '\n    + \n    + test_expect_success 'stdin -z fails update with no old value' '\n    + \tprintf $F \"update $a\" \"$m\" >stdin &&\n    + \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: update $a: unexpected end of input when reading <oldvalue>\" err\n    ++\tgrep \"fatal: update $a: unexpected end of input when reading <old-oid>\" err\n    + '\n    + \n    + test_expect_success 'stdin -z fails update with too many arguments' '\n    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z fails delete with no ref' '\n    + test_expect_success 'stdin -z fails delete with no old value' '\n    + \tprintf $F \"delete $a\" >stdin &&\n    + \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: delete $a: unexpected end of input when reading <oldvalue>\" err\n    ++\tgrep \"fatal: delete $a: unexpected end of input when reading <old-oid>\" err\n    + '\n    + \n    + test_expect_success 'stdin -z fails delete with too many arguments' '\n    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z fails verify with too many arguments' '\n    + test_expect_success 'stdin -z fails verify with no old value' '\n    + \tprintf $F \"verify $a\" >stdin &&\n    + \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: verify $a: unexpected end of input when reading <oldvalue>\" err\n    ++\tgrep \"fatal: verify $a: unexpected end of input when reading <old-oid>\" err\n    + '\n    + \n    + test_expect_success 'stdin -z fails option with unknown name' '\n    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z update ref fails with wrong old value' '\n    + test_expect_success 'stdin -z update ref fails with bad old value' '\n    + \tprintf $F \"update $c\" \"$m\" \"does-not-exist\" >stdin &&\n    + \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: update $c: invalid <oldvalue>: does-not-exist\" err &&\n    ++\tgrep \"fatal: update $c: invalid <old-oid>: does-not-exist\" err &&\n    + \ttest_must_fail git rev-parse --verify -q $c\n    + '\n    + \n    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z create ref fails with bad new value' '\n    + \tgit update-ref -d \"$c\" &&\n    + \tprintf $F \"create $c\" \"does-not-exist\" >stdin &&\n    + \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: create $c: invalid <newvalue>: does-not-exist\" err &&\n    ++\tgrep \"fatal: create $c: invalid <new-oid>: does-not-exist\" err &&\n    + \ttest_must_fail git rev-parse --verify -q $c\n    + '\n    + \n    + test_expect_success 'stdin -z create ref fails with empty new value' '\n    + \tprintf $F \"create $c\" \"\" >stdin &&\n    + \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: create $c: missing <newvalue>\" err &&\n    ++\tgrep \"fatal: create $c: missing <new-oid>\" err &&\n    + \ttest_must_fail git rev-parse --verify -q $c\n    + '\n    + \n    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z delete ref fails with wrong old value' '\n    + test_expect_success 'stdin -z delete ref fails with zero old value' '\n    + \tprintf $F \"delete $a\" \"$Z\" >stdin &&\n    + \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n    +-\tgrep \"fatal: delete $a: zero <oldvalue>\" err &&\n    ++\tgrep \"fatal: delete $a: zero <old-oid>\" err &&\n    + \tgit rev-parse $m >expect &&\n    + \tgit rev-parse $a >actual &&\n    + \ttest_cmp expect actual\n2:  17950e0693 = 2:  972faccb4a githooks: use {old,new}-oid instead of {old,new}-value\n\n[1]: https://public-inbox.org/git/20240330224623.579457-1-knayak@gitlab.com/T/#m7bb4d1f44b656d7cfb73ed3220b990aa6d1ac247\n[2]: https://public-inbox.org/git/20240330224623.579457-1-knayak@gitlab.com/T/#t\n\nKarthik Nayak (2):\n  update-ref: use {old,new}-oid instead of {old,new}value\n  githooks: use {old,new}-oid instead of {old,new}-value\n\n Documentation/git-update-ref.txt | 58 ++++++++++++++++----------------\n Documentation/githooks.txt       | 16 ++++-----\n builtin/update-ref.c             | 26 +++++++-------\n t/t1400-update-ref.sh            | 34 +++++++++----------\n 4 files changed, 67 insertions(+), 67 deletions(-)\n\n-- \n2.43.GIT\n\n"},{"id":"492021","messageId":"20240402064915.191104-3-knayak@gitlab.com","threadId":"61242","inReplyTo":"20240402064915.191104-1-knayak@gitlab.com","subject":"[PATCH v2 2/2] githooks: use {old,new}-oid instead of {old,new}-value","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-04-02T06:49:15Z","receivedAt":"2024-04-02T06:49:22Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"From: Karthik Nayak <karthik.188@gmail.com>\n\nSimilar to the previous commit, rename {old,new}-value in the 'githooks'\ndocumentation to {old,new}-oid. This improves clarity and also ensures\nconsistency within the document.\n\nSigned-off-by: Karthik Nayak <karthik.188@gmail.com>\n---\n Documentation/githooks.txt | 16 ++++++++--------\n 1 file changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/githooks.txt b/Documentation/githooks.txt\nindex 37f91d5b50..ee9b92c90d 100644\n--- a/Documentation/githooks.txt\n+++ b/Documentation/githooks.txt\n@@ -275,12 +275,12 @@ This hook executes once for the receive operation. It takes no\n arguments, but for each ref to be updated it receives on standard\n input a line of the format:\n \n-  <old-value> SP <new-value> SP <ref-name> LF\n+  <old-oid> SP <new-oid> SP <ref-name> LF\n \n-where `<old-value>` is the old object name stored in the ref,\n-`<new-value>` is the new object name to be stored in the ref and\n+where `<old-oid>` is the old object name stored in the ref,\n+`<new-oid>` is the new object name to be stored in the ref and\n `<ref-name>` is the full name of the ref.\n-When creating a new ref, `<old-value>` is the all-zeroes object name.\n+When creating a new ref, `<old-oid>` is the all-zeroes object name.\n \n If the hook exits with non-zero status, none of the refs will be\n updated. If the hook exits with zero, updating of individual refs can\n@@ -503,13 +503,13 @@ given reference transaction is in:\n For each reference update that was added to the transaction, the hook\n receives on standard input a line of the format:\n \n-  <old-value> SP <new-value> SP <ref-name> LF\n+  <old-oid> SP <new-oid> SP <ref-name> LF\n \n-where `<old-value>` is the old object name passed into the reference\n-transaction, `<new-value>` is the new object name to be stored in the\n+where `<old-oid>` is the old object name passed into the reference\n+transaction, `<new-oid>` is the new object name to be stored in the\n ref and `<ref-name>` is the full name of the ref. When force updating\n the reference regardless of its current value or when the reference is\n-to be created anew, `<old-value>` is the all-zeroes object name. To\n+to be created anew, `<old-oid>` is the all-zeroes object name. To\n distinguish these cases, you can inspect the current value of\n `<ref-name>` via `git rev-parse`.\n \n-- \n2.43.GIT\n\n"},{"id":"492022","messageId":"20240402064915.191104-2-knayak@gitlab.com","threadId":"61242","inReplyTo":"20240402064915.191104-1-knayak@gitlab.com","subject":"[PATCH v2 1/2] update-ref: use {old,new}-oid instead of {old,new}value","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-04-02T06:49:14Z","receivedAt":"2024-04-02T06:49:22Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"From: Karthik Nayak <karthik.188@gmail.com>\n\nThe `git-update-ref` command is used to modify references. The usage of\n{old,new}value in the documentation refers to the OIDs. This is fine\nsince the command only works with regular references which hold OIDs.\nBut if the command is updated to support symrefs, we'd also be dealing\nwith {old,new}-refs.\n\nTo improve clarity around what exactly {old,new}value mean, let's rename\nit to {old,new}-oid.\n\nSigned-off-by: Karthik Nayak <karthik.188@gmail.com>\n---\n Documentation/git-update-ref.txt | 58 ++++++++++++++++----------------\n builtin/update-ref.c             | 26 +++++++-------\n t/t1400-update-ref.sh            | 34 +++++++++----------\n 3 files changed, 59 insertions(+), 59 deletions(-)\n\ndiff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt\nindex 0561808cca..374a2ebd2b 100644\n--- a/Documentation/git-update-ref.txt\n+++ b/Documentation/git-update-ref.txt\n@@ -8,21 +8,21 @@ git-update-ref - Update the object name stored in a ref safely\n SYNOPSIS\n --------\n [verse]\n-'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<oldvalue>] | [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z])\n+'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<old-oid>] | [--create-reflog] <ref> <new-oid> [<old-oid>] | --stdin [-z])\n \n DESCRIPTION\n -----------\n-Given two arguments, stores the <newvalue> in the <ref>, possibly\n+Given two arguments, stores the <new-oid> in the <ref>, possibly\n dereferencing the symbolic refs.  E.g. `git update-ref HEAD\n-<newvalue>` updates the current branch head to the new object.\n+<new-oid>` updates the current branch head to the new object.\n \n-Given three arguments, stores the <newvalue> in the <ref>,\n+Given three arguments, stores the <new-oid> in the <ref>,\n possibly dereferencing the symbolic refs, after verifying that\n-the current value of the <ref> matches <oldvalue>.\n-E.g. `git update-ref refs/heads/master <newvalue> <oldvalue>`\n-updates the master branch head to <newvalue> only if its current\n-value is <oldvalue>.  You can specify 40 \"0\" or an empty string\n-as <oldvalue> to make sure that the ref you are creating does\n+the current value of the <ref> matches <old-oid>.\n+E.g. `git update-ref refs/heads/master <new-oid> <old-oid>`\n+updates the master branch head to <new-oid> only if its current\n+value is <old-oid>.  You can specify 40 \"0\" or an empty string\n+as <old-oid> to make sure that the ref you are creating does\n not exist.\n \n It also allows a \"ref\" file to be a symbolic pointer to another\n@@ -56,15 +56,15 @@ ref symlink to some other tree, if you have copied a whole\n archive by creating a symlink tree).\n \n With `-d` flag, it deletes the named <ref> after verifying it\n-still contains <oldvalue>.\n+still contains <old-oid>.\n \n With `--stdin`, update-ref reads instructions from standard input and\n performs all modifications together.  Specify commands of the form:\n \n-\tupdate SP <ref> SP <newvalue> [SP <oldvalue>] LF\n-\tcreate SP <ref> SP <newvalue> LF\n-\tdelete SP <ref> [SP <oldvalue>] LF\n-\tverify SP <ref> [SP <oldvalue>] LF\n+\tupdate SP <ref> SP <new-oid> [SP <old-oid>] LF\n+\tcreate SP <ref> SP <new-oid> LF\n+\tdelete SP <ref> [SP <old-oid>] LF\n+\tverify SP <ref> [SP <old-oid>] LF\n \toption SP <opt> LF\n \tstart LF\n \tprepare LF\n@@ -82,10 +82,10 @@ specify a missing value, omit the value and its preceding SP entirely.\n Alternatively, use `-z` to specify in NUL-terminated format, without\n quoting:\n \n-\tupdate SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL\n-\tcreate SP <ref> NUL <newvalue> NUL\n-\tdelete SP <ref> NUL [<oldvalue>] NUL\n-\tverify SP <ref> NUL [<oldvalue>] NUL\n+\tupdate SP <ref> NUL <new-oid> NUL [<old-oid>] NUL\n+\tcreate SP <ref> NUL <new-oid> NUL\n+\tdelete SP <ref> NUL [<old-oid>] NUL\n+\tverify SP <ref> NUL [<old-oid>] NUL\n \toption SP <opt> NUL\n \tstart NUL\n \tprepare NUL\n@@ -100,22 +100,22 @@ recognizes as an object name.  Commands in any other format or a\n repeated <ref> produce an error.  Command meanings are:\n \n update::\n-\tSet <ref> to <newvalue> after verifying <oldvalue>, if given.\n-\tSpecify a zero <newvalue> to ensure the ref does not exist\n-\tafter the update and/or a zero <oldvalue> to make sure the\n+\tSet <ref> to <new-oid> after verifying <old-oid>, if given.\n+\tSpecify a zero <new-oid> to ensure the ref does not exist\n+\tafter the update and/or a zero <old-oid> to make sure the\n \tref does not exist before the update.\n \n create::\n-\tCreate <ref> with <newvalue> after verifying it does not\n-\texist.  The given <newvalue> may not be zero.\n+\tCreate <ref> with <new-oid> after verifying it does not\n+\texist.  The given <new-oid> may not be zero.\n \n delete::\n-\tDelete <ref> after verifying it exists with <oldvalue>, if\n-\tgiven.  If given, <oldvalue> may not be zero.\n+\tDelete <ref> after verifying it exists with <old-oid>, if\n+\tgiven.  If given, <old-oid> may not be zero.\n \n verify::\n-\tVerify <ref> against <oldvalue> but do not change it.  If\n-\t<oldvalue> is zero or missing, the ref must not exist.\n+\tVerify <ref> against <old-oid> but do not change it.  If\n+\t<old-oid> is zero or missing, the ref must not exist.\n \n option::\n \tModify the behavior of the next command naming a <ref>.\n@@ -141,7 +141,7 @@ abort::\n \tAbort the transaction, releasing all locks if the transaction is in\n \tprepared state.\n \n-If all <ref>s can be locked with matching <oldvalue>s\n+If all <ref>s can be locked with matching <old-oid>s\n simultaneously, all modifications are performed.  Otherwise, no\n modifications are performed.  Note that while each individual\n <ref> is updated or deleted atomically, a concurrent reader may\n@@ -161,7 +161,7 @@ formatted as:\n \n Where \"oldsha1\" is the 40 character hexadecimal value previously\n stored in <ref>, \"newsha1\" is the 40 character hexadecimal value of\n-<newvalue> and \"committer\" is the committer's name, email address\n+<new-oid> and \"committer\" is the committer's name, email address\n and date in the standard Git committer ident format.\n \n Optionally with -m:\ndiff --git a/builtin/update-ref.c b/builtin/update-ref.c\nindex 61338a01ec..e46afbc46d 100644\n--- a/builtin/update-ref.c\n+++ b/builtin/update-ref.c\n@@ -9,8 +9,8 @@\n #include \"repository.h\"\n \n static const char * const git_update_ref_usage[] = {\n-\tN_(\"git update-ref [<options>] -d <refname> [<old-val>]\"),\n-\tN_(\"git update-ref [<options>]    <refname> <new-val> [<old-val>]\"),\n+\tN_(\"git update-ref [<options>] -d <refname> [<old-oid>]\"),\n+\tN_(\"git update-ref [<options>]    <refname> <new-oid> [<old-oid>]\"),\n \tN_(\"git update-ref [<options>] --stdin [-z]\"),\n \tNULL\n };\n@@ -77,14 +77,14 @@ static char *parse_refname(const char **next)\n }\n \n /*\n- * The value being parsed is <oldvalue> (as opposed to <newvalue>; the\n+ * The value being parsed is <old-oid> (as opposed to <new-oid>; the\n  * difference affects which error messages are generated):\n  */\n #define PARSE_SHA1_OLD 0x01\n \n /*\n  * For backwards compatibility, accept an empty string for update's\n- * <newvalue> in binary mode to be equivalent to specifying zeros.\n+ * <new-oid> in binary mode to be equivalent to specifying zeros.\n  */\n #define PARSE_SHA1_ALLOW_EMPTY 0x02\n \n@@ -140,7 +140,7 @@ static int parse_next_oid(const char **next, const char *end,\n \t\t\t\tgoto invalid;\n \t\t} else if (flags & PARSE_SHA1_ALLOW_EMPTY) {\n \t\t\t/* With -z, treat an empty value as all zeros: */\n-\t\t\twarning(\"%s %s: missing <newvalue>, treating as zero\",\n+\t\t\twarning(\"%s %s: missing <new-oid>, treating as zero\",\n \t\t\t\tcommand, refname);\n \t\t\toidclr(oid);\n \t\t} else {\n@@ -158,14 +158,14 @@ static int parse_next_oid(const char **next, const char *end,\n \n  invalid:\n \tdie(flags & PARSE_SHA1_OLD ?\n-\t    \"%s %s: invalid <oldvalue>: %s\" :\n-\t    \"%s %s: invalid <newvalue>: %s\",\n+\t    \"%s %s: invalid <old-oid>: %s\" :\n+\t    \"%s %s: invalid <new-oid>: %s\",\n \t    command, refname, arg.buf);\n \n  eof:\n \tdie(flags & PARSE_SHA1_OLD ?\n-\t    \"%s %s: unexpected end of input when reading <oldvalue>\" :\n-\t    \"%s %s: unexpected end of input when reading <newvalue>\",\n+\t    \"%s %s: unexpected end of input when reading <old-oid>\" :\n+\t    \"%s %s: unexpected end of input when reading <new-oid>\",\n \t    command, refname);\n }\n \n@@ -194,7 +194,7 @@ static void parse_cmd_update(struct ref_transaction *transaction,\n \n \tif (parse_next_oid(&next, end, &new_oid, \"update\", refname,\n \t\t\t   PARSE_SHA1_ALLOW_EMPTY))\n-\t\tdie(\"update %s: missing <newvalue>\", refname);\n+\t\tdie(\"update %s: missing <new-oid>\", refname);\n \n \thave_old = !parse_next_oid(&next, end, &old_oid, \"update\", refname,\n \t\t\t\t   PARSE_SHA1_OLD);\n@@ -225,10 +225,10 @@ static void parse_cmd_create(struct ref_transaction *transaction,\n \t\tdie(\"create: missing <ref>\");\n \n \tif (parse_next_oid(&next, end, &new_oid, \"create\", refname, 0))\n-\t\tdie(\"create %s: missing <newvalue>\", refname);\n+\t\tdie(\"create %s: missing <new-oid>\", refname);\n \n \tif (is_null_oid(&new_oid))\n-\t\tdie(\"create %s: zero <newvalue>\", refname);\n+\t\tdie(\"create %s: zero <new-oid>\", refname);\n \n \tif (*next != line_termination)\n \t\tdie(\"create %s: extra input: %s\", refname, next);\n@@ -260,7 +260,7 @@ static void parse_cmd_delete(struct ref_transaction *transaction,\n \t\thave_old = 0;\n \t} else {\n \t\tif (is_null_oid(&old_oid))\n-\t\t\tdie(\"delete %s: zero <oldvalue>\", refname);\n+\t\t\tdie(\"delete %s: zero <old-oid>\", refname);\n \t\thave_old = 1;\n \t}\n \ndiff --git a/t/t1400-update-ref.sh b/t/t1400-update-ref.sh\nindex 6ebc3ef945..ec3443cc87 100755\n--- a/t/t1400-update-ref.sh\n+++ b/t/t1400-update-ref.sh\n@@ -622,7 +622,7 @@ test_expect_success 'stdin fails create with no ref' '\n test_expect_success 'stdin fails create with no new value' '\n \techo \"create $a\" >stdin &&\n \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n-\tgrep \"fatal: create $a: missing <newvalue>\" err\n+\tgrep \"fatal: create $a: missing <new-oid>\" err\n '\n \n test_expect_success 'stdin fails create with too many arguments' '\n@@ -640,7 +640,7 @@ test_expect_success 'stdin fails update with no ref' '\n test_expect_success 'stdin fails update with no new value' '\n \techo \"update $a\" >stdin &&\n \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n-\tgrep \"fatal: update $a: missing <newvalue>\" err\n+\tgrep \"fatal: update $a: missing <new-oid>\" err\n '\n \n test_expect_success 'stdin fails update with too many arguments' '\n@@ -765,21 +765,21 @@ test_expect_success 'stdin update ref fails with wrong old value' '\n test_expect_success 'stdin update ref fails with bad old value' '\n \techo \"update $c $m does-not-exist\" >stdin &&\n \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n-\tgrep \"fatal: update $c: invalid <oldvalue>: does-not-exist\" err &&\n+\tgrep \"fatal: update $c: invalid <old-oid>: does-not-exist\" err &&\n \ttest_must_fail git rev-parse --verify -q $c\n '\n \n test_expect_success 'stdin create ref fails with bad new value' '\n \techo \"create $c does-not-exist\" >stdin &&\n \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n-\tgrep \"fatal: create $c: invalid <newvalue>: does-not-exist\" err &&\n+\tgrep \"fatal: create $c: invalid <new-oid>: does-not-exist\" err &&\n \ttest_must_fail git rev-parse --verify -q $c\n '\n \n test_expect_success 'stdin create ref fails with zero new value' '\n \techo \"create $c \" >stdin &&\n \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n-\tgrep \"fatal: create $c: zero <newvalue>\" err &&\n+\tgrep \"fatal: create $c: zero <new-oid>\" err &&\n \ttest_must_fail git rev-parse --verify -q $c\n '\n \n@@ -803,7 +803,7 @@ test_expect_success 'stdin delete ref fails with wrong old value' '\n test_expect_success 'stdin delete ref fails with zero old value' '\n \techo \"delete $a \" >stdin &&\n \ttest_must_fail git update-ref --stdin <stdin 2>err &&\n-\tgrep \"fatal: delete $a: zero <oldvalue>\" err &&\n+\tgrep \"fatal: delete $a: zero <old-oid>\" err &&\n \tgit rev-parse $m >expect &&\n \tgit rev-parse $a >actual &&\n \ttest_cmp expect actual\n@@ -1027,7 +1027,7 @@ test_expect_success 'stdin -z fails create with no ref' '\n test_expect_success 'stdin -z fails create with no new value' '\n \tprintf $F \"create $a\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: create $a: unexpected end of input when reading <newvalue>\" err\n+\tgrep \"fatal: create $a: unexpected end of input when reading <new-oid>\" err\n '\n \n test_expect_success 'stdin -z fails create with too many arguments' '\n@@ -1045,27 +1045,27 @@ test_expect_success 'stdin -z fails update with no ref' '\n test_expect_success 'stdin -z fails update with too few args' '\n \tprintf $F \"update $a\" \"$m\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: update $a: unexpected end of input when reading <oldvalue>\" err\n+\tgrep \"fatal: update $a: unexpected end of input when reading <old-oid>\" err\n '\n \n test_expect_success 'stdin -z emits warning with empty new value' '\n \tgit update-ref $a $m &&\n \tprintf $F \"update $a\" \"\" \"\" >stdin &&\n \tgit update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"warning: update $a: missing <newvalue>, treating as zero\" err &&\n+\tgrep \"warning: update $a: missing <new-oid>, treating as zero\" err &&\n \ttest_must_fail git rev-parse --verify -q $a\n '\n \n test_expect_success 'stdin -z fails update with no new value' '\n \tprintf $F \"update $a\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: update $a: unexpected end of input when reading <newvalue>\" err\n+\tgrep \"fatal: update $a: unexpected end of input when reading <new-oid>\" err\n '\n \n test_expect_success 'stdin -z fails update with no old value' '\n \tprintf $F \"update $a\" \"$m\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: update $a: unexpected end of input when reading <oldvalue>\" err\n+\tgrep \"fatal: update $a: unexpected end of input when reading <old-oid>\" err\n '\n \n test_expect_success 'stdin -z fails update with too many arguments' '\n@@ -1083,7 +1083,7 @@ test_expect_success 'stdin -z fails delete with no ref' '\n test_expect_success 'stdin -z fails delete with no old value' '\n \tprintf $F \"delete $a\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: delete $a: unexpected end of input when reading <oldvalue>\" err\n+\tgrep \"fatal: delete $a: unexpected end of input when reading <old-oid>\" err\n '\n \n test_expect_success 'stdin -z fails delete with too many arguments' '\n@@ -1101,7 +1101,7 @@ test_expect_success 'stdin -z fails verify with too many arguments' '\n test_expect_success 'stdin -z fails verify with no old value' '\n \tprintf $F \"verify $a\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: verify $a: unexpected end of input when reading <oldvalue>\" err\n+\tgrep \"fatal: verify $a: unexpected end of input when reading <old-oid>\" err\n '\n \n test_expect_success 'stdin -z fails option with unknown name' '\n@@ -1160,7 +1160,7 @@ test_expect_success 'stdin -z update ref fails with wrong old value' '\n test_expect_success 'stdin -z update ref fails with bad old value' '\n \tprintf $F \"update $c\" \"$m\" \"does-not-exist\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: update $c: invalid <oldvalue>: does-not-exist\" err &&\n+\tgrep \"fatal: update $c: invalid <old-oid>: does-not-exist\" err &&\n \ttest_must_fail git rev-parse --verify -q $c\n '\n \n@@ -1178,14 +1178,14 @@ test_expect_success 'stdin -z create ref fails with bad new value' '\n \tgit update-ref -d \"$c\" &&\n \tprintf $F \"create $c\" \"does-not-exist\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: create $c: invalid <newvalue>: does-not-exist\" err &&\n+\tgrep \"fatal: create $c: invalid <new-oid>: does-not-exist\" err &&\n \ttest_must_fail git rev-parse --verify -q $c\n '\n \n test_expect_success 'stdin -z create ref fails with empty new value' '\n \tprintf $F \"create $c\" \"\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: create $c: missing <newvalue>\" err &&\n+\tgrep \"fatal: create $c: missing <new-oid>\" err &&\n \ttest_must_fail git rev-parse --verify -q $c\n '\n \n@@ -1209,7 +1209,7 @@ test_expect_success 'stdin -z delete ref fails with wrong old value' '\n test_expect_success 'stdin -z delete ref fails with zero old value' '\n \tprintf $F \"delete $a\" \"$Z\" >stdin &&\n \ttest_must_fail git update-ref -z --stdin <stdin 2>err &&\n-\tgrep \"fatal: delete $a: zero <oldvalue>\" err &&\n+\tgrep \"fatal: delete $a: zero <old-oid>\" err &&\n \tgit rev-parse $m >expect &&\n \tgit rev-parse $a >actual &&\n \ttest_cmp expect actual\n-- \n2.43.GIT\n\n"},{"id":"492023","messageId":"CAOLa=ZS1OUCtPTC2LGpgU0K7U-ryNkkKFLrUqnuz=tcpU0NE-g@mail.gmail.com","threadId":"61242","inReplyTo":"xmqqr0fo7kop.fsf@gitster.g","subject":"Re: [PATCH 1/2] update-ref: use {old,new}-oid instead of {old,new}value","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-04-02T06:50:11Z","receivedAt":"2024-04-02T06:50:13Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Karthik Nayak <karthik.188@gmail.com> writes:\n>\n>>> Did you run t1400 after this update?  There may be other tests that\n>>> the message update is breaking but that was the first one I noticed.\n>>\n>> I definitely didn't. It totally slipped my mind, I was thinking that I\n>> only modified the *.txt files. I will send in a new version after\n>> ensuring all tests are fixed.\n>\n> Here is what I have.\n>\n\nYup, this should fix it. I've sent in v2 with the same fix.\n"},{"id":"492024","messageId":"ZgusInW9NSjtRiOw@tanuki","threadId":"61242","inReplyTo":"20240402064915.191104-1-knayak@gitlab.com","subject":"Re: [PATCH v2 0/2] improve documentation around git-update-ref","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-04-02T06:56:34Z","receivedAt":"2024-04-02T06:56:42Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Apr 02, 2024 at 08:49:13AM +0200, Karthik Nayak wrote:\n> From: Karthik Nayak <karthik.188@gmail.com>\n> \n> This patch series was derived out of the discussion [1] around my other\n> patch series to add symref support for `git-update-ref(1)` [2].\n> \n> The aim of these patches is to improve clarity around OIDs in the\n> documentation. This makes it easier to draw parallels between regular\n> ref updates and symref updates. The symref patch series will be rebased\n> on top of this in the upcoming version.\n\nThese patches look good to me, thanks!\n\nPatrick\n"}]}