mirrors/git
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'kn/clarify-update-ref-doc'

Browse Source 
Doc update, as a preparation to enhance "git update-ref --stdin".

* kn/clarify-update-ref-doc:
  githooks: use {old,new}-oid instead of {old,new}-value
  update-ref: use {old,new}-oid instead of {old,new}value
This commit is contained in:
Junio C Hamano
2024-04-10 10:00:08 -07:00
parent a4a1453ad1 5b1967a33c
commit 280b74ce18
4 changed files with 67 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
Documentation/git-update-ref.txt
View File

@ -8,21 +8,21 @@ git-update-ref - Update the object name stored in a ref safely
SYNOPSIS SYNOPSIS
-------- --------
[verse] [verse]
'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<oldvalue>] | [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z]) 'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<old-oid>] | [--create-reflog] <ref> <new-oid> [<old-oid>] | --stdin [-z])
DESCRIPTION DESCRIPTION
----------- -----------
Given two arguments, stores the <newvalue> in the <ref>, possibly Given two arguments, stores the <new-oid> in the <ref>, possibly
dereferencing the symbolic refs. E.g. `git update-ref HEAD dereferencing the symbolic refs. E.g. `git update-ref HEAD
<newvalue>` updates the current branch head to the new object. <new-oid>` updates the current branch head to the new object.
Given three arguments, stores the <newvalue> in the <ref>, Given three arguments, stores the <new-oid> in the <ref>,
possibly dereferencing the symbolic refs, after verifying that possibly dereferencing the symbolic refs, after verifying that
the current value of the <ref> matches <oldvalue>. the current value of the <ref> matches <old-oid>.
E.g. `git update-ref refs/heads/master <newvalue> <oldvalue>` E.g. `git update-ref refs/heads/master <new-oid> <old-oid>`
updates the master branch head to <newvalue> only if its current updates the master branch head to <new-oid> only if its current
value is <oldvalue>. You can specify 40 "0" or an empty string value is <old-oid>. You can specify 40 "0" or an empty string
as <oldvalue> to make sure that the ref you are creating does as <old-oid> to make sure that the ref you are creating does
not exist. not exist.
It also allows a "ref" file to be a symbolic pointer to another It also allows a "ref" file to be a symbolic pointer to another
@ -56,15 +56,15 @@ ref symlink to some other tree, if you have copied a whole
archive by creating a symlink tree). archive by creating a symlink tree).
With `-d` flag, it deletes the named <ref> after verifying it With `-d` flag, it deletes the named <ref> after verifying it
still contains <oldvalue>. still contains <old-oid>.
With `--stdin`, update-ref reads instructions from standard input and With `--stdin`, update-ref reads instructions from standard input and
performs all modifications together. Specify commands of the form: performs all modifications together. Specify commands of the form:
update SP <ref> SP <newvalue> [SP <oldvalue>] LF update SP <ref> SP <new-oid> [SP <old-oid>] LF
create SP <ref> SP <newvalue> LF create SP <ref> SP <new-oid> LF
delete SP <ref> [SP <oldvalue>] LF delete SP <ref> [SP <old-oid>] LF
verify SP <ref> [SP <oldvalue>] LF verify SP <ref> [SP <old-oid>] LF
option SP <opt> LF option SP <opt> LF
start LF start LF
prepare LF prepare LF
@ -82,10 +82,10 @@ specify a missing value, omit the value and its preceding SP entirely.
Alternatively, use `-z` to specify in NUL-terminated format, without Alternatively, use `-z` to specify in NUL-terminated format, without
quoting: quoting:
update SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL update SP <ref> NUL <new-oid> NUL [<old-oid>] NUL
create SP <ref> NUL <newvalue> NUL create SP <ref> NUL <new-oid> NUL
delete SP <ref> NUL [<oldvalue>] NUL delete SP <ref> NUL [<old-oid>] NUL
verify SP <ref> NUL [<oldvalue>] NUL verify SP <ref> NUL [<old-oid>] NUL
option SP <opt> NUL option SP <opt> NUL
start NUL start NUL
prepare NUL prepare NUL
@ -100,22 +100,22 @@ recognizes as an object name. Commands in any other format or a
repeated <ref> produce an error. Command meanings are: repeated <ref> produce an error. Command meanings are:
update:: update::
Set <ref> to <newvalue> after verifying <oldvalue>, if given. Set <ref> to <new-oid> after verifying <old-oid>, if given.
Specify a zero <newvalue> to ensure the ref does not exist Specify a zero <new-oid> to ensure the ref does not exist
after the update and/or a zero <oldvalue> to make sure the after the update and/or a zero <old-oid> to make sure the
ref does not exist before the update. ref does not exist before the update.
create:: create::
Create <ref> with <newvalue> after verifying it does not Create <ref> with <new-oid> after verifying it does not
exist. The given <newvalue> may not be zero. exist. The given <new-oid> may not be zero.
delete:: delete::
Delete <ref> after verifying it exists with <oldvalue>, if Delete <ref> after verifying it exists with <old-oid>, if
given. If given, <oldvalue> may not be zero. given. If given, <old-oid> may not be zero.
verify:: verify::
Verify <ref> against <oldvalue> but do not change it. If Verify <ref> against <old-oid> but do not change it. If
<oldvalue> is zero or missing, the ref must not exist. <old-oid> is zero or missing, the ref must not exist.
option:: option::
Modify the behavior of the next command naming a <ref>. Modify the behavior of the next command naming a <ref>.
@ -141,7 +141,7 @@ abort::
Abort the transaction, releasing all locks if the transaction is in Abort the transaction, releasing all locks if the transaction is in
prepared state. prepared state.
If all <ref>s can be locked with matching <oldvalue>s If all <ref>s can be locked with matching <old-oid>s
simultaneously, all modifications are performed. Otherwise, no simultaneously, all modifications are performed. Otherwise, no
modifications are performed. Note that while each individual modifications are performed. Note that while each individual
<ref> is updated or deleted atomically, a concurrent reader may <ref> is updated or deleted atomically, a concurrent reader may
@ -161,7 +161,7 @@ formatted as:
Where "oldsha1" is the 40 character hexadecimal value previously Where "oldsha1" is the 40 character hexadecimal value previously
stored in <ref>, "newsha1" is the 40 character hexadecimal value of stored in <ref>, "newsha1" is the 40 character hexadecimal value of
<newvalue> and "committer" is the committer's name, email address <new-oid> and "committer" is the committer's name, email address
and date in the standard Git committer ident format. and date in the standard Git committer ident format.
Optionally with -m: Optionally with -m:

16
Documentation/githooks.txt
View File

@ -275,12 +275,12 @@ This hook executes once for the receive operation. It takes no
arguments, but for each ref to be updated it receives on standard arguments, but for each ref to be updated it receives on standard
input a line of the format: input a line of the format:
<old-value> SP <new-value> SP <ref-name> LF <old-oid> SP <new-oid> SP <ref-name> LF
where `<old-value>` is the old object name stored in the ref, where `<old-oid>` is the old object name stored in the ref,
`<new-value>` is the new object name to be stored in the ref and `<new-oid>` is the new object name to be stored in the ref and
`<ref-name>` is the full name of the ref. `<ref-name>` is the full name of the ref.
When creating a new ref, `<old-value>` is the all-zeroes object name. When creating a new ref, `<old-oid>` is the all-zeroes object name.
If the hook exits with non-zero status, none of the refs will be If the hook exits with non-zero status, none of the refs will be
updated. If the hook exits with zero, updating of individual refs can updated. If the hook exits with zero, updating of individual refs can
@ -503,13 +503,13 @@ given reference transaction is in:
For each reference update that was added to the transaction, the hook For each reference update that was added to the transaction, the hook
receives on standard input a line of the format: receives on standard input a line of the format:
<old-value> SP <new-value> SP <ref-name> LF <old-oid> SP <new-oid> SP <ref-name> LF
where `<old-value>` is the old object name passed into the reference where `<old-oid>` is the old object name passed into the reference
transaction, `<new-value>` is the new object name to be stored in the transaction, `<new-oid>` is the new object name to be stored in the
ref and `<ref-name>` is the full name of the ref. When force updating ref and `<ref-name>` is the full name of the ref. When force updating
the reference regardless of its current value or when the reference is the reference regardless of its current value or when the reference is
to be created anew, `<old-value>` is the all-zeroes object name. To to be created anew, `<old-oid>` is the all-zeroes object name. To
distinguish these cases, you can inspect the current value of distinguish these cases, you can inspect the current value of
`<ref-name>` via `git rev-parse`. `<ref-name>` via `git rev-parse`.

26
builtin/update-ref.c
View File

@ -9,8 +9,8 @@
#include "repository.h" #include "repository.h"
static const char * const git_update_ref_usage[] = { static const char * const git_update_ref_usage[] = {
N_("git update-ref [<options>] -d <refname> [<old-val>]"), N_("git update-ref [<options>] -d <refname> [<old-oid>]"),
N_("git update-ref [<options>] <refname> <new-val> [<old-val>]"), N_("git update-ref [<options>] <refname> <new-oid> [<old-oid>]"),
N_("git update-ref [<options>] --stdin [-z]"), N_("git update-ref [<options>] --stdin [-z]"),
NULL NULL
}; };
@ -77,14 +77,14 @@ static char *parse_refname(const char **next)
} }
/* /*
* The value being parsed is <oldvalue> (as opposed to <newvalue>; the * The value being parsed is <old-oid> (as opposed to <new-oid>; the
* difference affects which error messages are generated): * difference affects which error messages are generated):
*/ */
#define PARSE_SHA1_OLD 0x01 #define PARSE_SHA1_OLD 0x01
/* /*
* For backwards compatibility, accept an empty string for update's * For backwards compatibility, accept an empty string for update's
* <newvalue> in binary mode to be equivalent to specifying zeros. * <new-oid> in binary mode to be equivalent to specifying zeros.
*/ */
#define PARSE_SHA1_ALLOW_EMPTY 0x02 #define PARSE_SHA1_ALLOW_EMPTY 0x02
@ -140,7 +140,7 @@ static int parse_next_oid(const char **next, const char *end,
goto invalid; goto invalid;
} else if (flags & PARSE_SHA1_ALLOW_EMPTY) { } else if (flags & PARSE_SHA1_ALLOW_EMPTY) {
/* With -z, treat an empty value as all zeros: */ /* With -z, treat an empty value as all zeros: */
warning("%s %s: missing <newvalue>, treating as zero", warning("%s %s: missing <new-oid>, treating as zero",
command, refname); command, refname);
oidclr(oid); oidclr(oid);
} else { } else {
@ -158,14 +158,14 @@ static int parse_next_oid(const char **next, const char *end,
invalid: invalid:
die(flags & PARSE_SHA1_OLD ? die(flags & PARSE_SHA1_OLD ?
"%s %s: invalid <oldvalue>: %s" : "%s %s: invalid <old-oid>: %s" :
"%s %s: invalid <newvalue>: %s", "%s %s: invalid <new-oid>: %s",
command, refname, arg.buf); command, refname, arg.buf);
eof: eof:
die(flags & PARSE_SHA1_OLD ? die(flags & PARSE_SHA1_OLD ?
"%s %s: unexpected end of input when reading <oldvalue>" : "%s %s: unexpected end of input when reading <old-oid>" :
"%s %s: unexpected end of input when reading <newvalue>", "%s %s: unexpected end of input when reading <new-oid>",
command, refname); command, refname);
} }
@ -194,7 +194,7 @@ static void parse_cmd_update(struct ref_transaction *transaction,
if (parse_next_oid(&next, end, &new_oid, "update", refname, if (parse_next_oid(&next, end, &new_oid, "update", refname,
PARSE_SHA1_ALLOW_EMPTY)) PARSE_SHA1_ALLOW_EMPTY))
die("update %s: missing <newvalue>", refname); die("update %s: missing <new-oid>", refname);
have_old = !parse_next_oid(&next, end, &old_oid, "update", refname, have_old = !parse_next_oid(&next, end, &old_oid, "update", refname,
PARSE_SHA1_OLD); PARSE_SHA1_OLD);
@ -225,10 +225,10 @@ static void parse_cmd_create(struct ref_transaction *transaction,
die("create: missing <ref>"); die("create: missing <ref>");
if (parse_next_oid(&next, end, &new_oid, "create", refname, 0)) if (parse_next_oid(&next, end, &new_oid, "create", refname, 0))
die("create %s: missing <newvalue>", refname); die("create %s: missing <new-oid>", refname);
if (is_null_oid(&new_oid)) if (is_null_oid(&new_oid))
die("create %s: zero <newvalue>", refname); die("create %s: zero <new-oid>", refname);
if (*next != line_termination) if (*next != line_termination)
die("create %s: extra input: %s", refname, next); die("create %s: extra input: %s", refname, next);
@ -260,7 +260,7 @@ static void parse_cmd_delete(struct ref_transaction *transaction,
have_old = 0; have_old = 0;
} else { } else {
if (is_null_oid(&old_oid)) if (is_null_oid(&old_oid))
die("delete %s: zero <oldvalue>", refname); die("delete %s: zero <old-oid>", refname);
have_old = 1; have_old = 1;
} }

34
t/t1400-update-ref.sh
View File

@ -622,7 +622,7 @@ test_expect_success 'stdin fails create with no ref' '
test_expect_success 'stdin fails create with no new value' ' test_expect_success 'stdin fails create with no new value' '
echo "create $a" >stdin && echo "create $a" >stdin &&
test_must_fail git update-ref --stdin <stdin 2>err && test_must_fail git update-ref --stdin <stdin 2>err &&
grep "fatal: create $a: missing <newvalue>" err grep "fatal: create $a: missing <new-oid>" err
' '
test_expect_success 'stdin fails create with too many arguments' ' test_expect_success 'stdin fails create with too many arguments' '
@ -640,7 +640,7 @@ test_expect_success 'stdin fails update with no ref' '
test_expect_success 'stdin fails update with no new value' ' test_expect_success 'stdin fails update with no new value' '
echo "update $a" >stdin && echo "update $a" >stdin &&
test_must_fail git update-ref --stdin <stdin 2>err && test_must_fail git update-ref --stdin <stdin 2>err &&
grep "fatal: update $a: missing <newvalue>" err grep "fatal: update $a: missing <new-oid>" err
' '
test_expect_success 'stdin fails update with too many arguments' ' test_expect_success 'stdin fails update with too many arguments' '
@ -765,21 +765,21 @@ test_expect_success 'stdin update ref fails with wrong old value' '
test_expect_success 'stdin update ref fails with bad old value' ' test_expect_success 'stdin update ref fails with bad old value' '
echo "update $c $m does-not-exist" >stdin && echo "update $c $m does-not-exist" >stdin &&
test_must_fail git update-ref --stdin <stdin 2>err && test_must_fail git update-ref --stdin <stdin 2>err &&
grep "fatal: update $c: invalid <oldvalue>: does-not-exist" err && grep "fatal: update $c: invalid <old-oid>: does-not-exist" err &&
test_must_fail git rev-parse --verify -q $c test_must_fail git rev-parse --verify -q $c
' '
test_expect_success 'stdin create ref fails with bad new value' ' test_expect_success 'stdin create ref fails with bad new value' '
echo "create $c does-not-exist" >stdin && echo "create $c does-not-exist" >stdin &&
test_must_fail git update-ref --stdin <stdin 2>err && test_must_fail git update-ref --stdin <stdin 2>err &&
grep "fatal: create $c: invalid <newvalue>: does-not-exist" err && grep "fatal: create $c: invalid <new-oid>: does-not-exist" err &&
test_must_fail git rev-parse --verify -q $c test_must_fail git rev-parse --verify -q $c
' '
test_expect_success 'stdin create ref fails with zero new value' ' test_expect_success 'stdin create ref fails with zero new value' '
echo "create $c " >stdin && echo "create $c " >stdin &&
test_must_fail git update-ref --stdin <stdin 2>err && test_must_fail git update-ref --stdin <stdin 2>err &&
grep "fatal: create $c: zero <newvalue>" err && grep "fatal: create $c: zero <new-oid>" err &&
test_must_fail git rev-parse --verify -q $c test_must_fail git rev-parse --verify -q $c
' '
@ -803,7 +803,7 @@ test_expect_success 'stdin delete ref fails with wrong old value' '
test_expect_success 'stdin delete ref fails with zero old value' ' test_expect_success 'stdin delete ref fails with zero old value' '
echo "delete $a " >stdin && echo "delete $a " >stdin &&
test_must_fail git update-ref --stdin <stdin 2>err && test_must_fail git update-ref --stdin <stdin 2>err &&
grep "fatal: delete $a: zero <oldvalue>" err && grep "fatal: delete $a: zero <old-oid>" err &&
git rev-parse $m >expect && git rev-parse $m >expect &&
git rev-parse $a >actual && git rev-parse $a >actual &&
test_cmp expect actual test_cmp expect actual
@ -1027,7 +1027,7 @@ test_expect_success 'stdin -z fails create with no ref' '
test_expect_success 'stdin -z fails create with no new value' ' test_expect_success 'stdin -z fails create with no new value' '
printf $F "create $a" >stdin && printf $F "create $a" >stdin &&
test_must_fail git update-ref -z --stdin <stdin 2>err && test_must_fail git update-ref -z --stdin <stdin 2>err &&
grep "fatal: create $a: unexpected end of input when reading <newvalue>" err grep "fatal: create $a: unexpected end of input when reading <new-oid>" err
' '
test_expect_success 'stdin -z fails create with too many arguments' ' test_expect_success 'stdin -z fails create with too many arguments' '
@ -1045,27 +1045,27 @@ test_expect_success 'stdin -z fails update with no ref' '
test_expect_success 'stdin -z fails update with too few args' ' test_expect_success 'stdin -z fails update with too few args' '
printf $F "update $a" "$m" >stdin && printf $F "update $a" "$m" >stdin &&
test_must_fail git update-ref -z --stdin <stdin 2>err && test_must_fail git update-ref -z --stdin <stdin 2>err &&
grep "fatal: update $a: unexpected end of input when reading <oldvalue>" err grep "fatal: update $a: unexpected end of input when reading <old-oid>" err
' '
test_expect_success 'stdin -z emits warning with empty new value' ' test_expect_success 'stdin -z emits warning with empty new value' '
git update-ref $a $m && git update-ref $a $m &&
printf $F "update $a" "" "" >stdin && printf $F "update $a" "" "" >stdin &&
git update-ref -z --stdin <stdin 2>err && git update-ref -z --stdin <stdin 2>err &&
grep "warning: update $a: missing <newvalue>, treating as zero" err && grep "warning: update $a: missing <new-oid>, treating as zero" err &&
test_must_fail git rev-parse --verify -q $a test_must_fail git rev-parse --verify -q $a
' '
test_expect_success 'stdin -z fails update with no new value' ' test_expect_success 'stdin -z fails update with no new value' '
printf $F "update $a" >stdin && printf $F "update $a" >stdin &&
test_must_fail git update-ref -z --stdin <stdin 2>err && test_must_fail git update-ref -z --stdin <stdin 2>err &&
grep "fatal: update $a: unexpected end of input when reading <newvalue>" err grep "fatal: update $a: unexpected end of input when reading <new-oid>" err
' '
test_expect_success 'stdin -z fails update with no old value' ' test_expect_success 'stdin -z fails update with no old value' '
printf $F "update $a" "$m" >stdin && printf $F "update $a" "$m" >stdin &&
test_must_fail git update-ref -z --stdin <stdin 2>err && test_must_fail git update-ref -z --stdin <stdin 2>err &&
grep "fatal: update $a: unexpected end of input when reading <oldvalue>" err grep "fatal: update $a: unexpected end of input when reading <old-oid>" err
' '
test_expect_success 'stdin -z fails update with too many arguments' ' test_expect_success 'stdin -z fails update with too many arguments' '
@ -1083,7 +1083,7 @@ test_expect_success 'stdin -z fails delete with no ref' '
test_expect_success 'stdin -z fails delete with no old value' ' test_expect_success 'stdin -z fails delete with no old value' '
printf $F "delete $a" >stdin && printf $F "delete $a" >stdin &&
test_must_fail git update-ref -z --stdin <stdin 2>err && test_must_fail git update-ref -z --stdin <stdin 2>err &&
grep "fatal: delete $a: unexpected end of input when reading <oldvalue>" err grep "fatal: delete $a: unexpected end of input when reading <old-oid>" err
' '
test_expect_success 'stdin -z fails delete with too many arguments' ' test_expect_success 'stdin -z fails delete with too many arguments' '
@ -1101,7 +1101,7 @@ test_expect_success 'stdin -z fails verify with too many arguments' '
test_expect_success 'stdin -z fails verify with no old value' ' test_expect_success 'stdin -z fails verify with no old value' '
printf $F "verify $a" >stdin && printf $F "verify $a" >stdin &&
test_must_fail git update-ref -z --stdin <stdin 2>err && test_must_fail git update-ref -z --stdin <stdin 2>err &&
grep "fatal: verify $a: unexpected end of input when reading <oldvalue>" err grep "fatal: verify $a: unexpected end of input when reading <old-oid>" err
' '
test_expect_success 'stdin -z fails option with unknown name' ' test_expect_success 'stdin -z fails option with unknown name' '
@ -1160,7 +1160,7 @@ test_expect_success 'stdin -z update ref fails with wrong old value' '
test_expect_success 'stdin -z update ref fails with bad old value' ' test_expect_success 'stdin -z update ref fails with bad old value' '
printf $F "update $c" "$m" "does-not-exist" >stdin && printf $F "update $c" "$m" "does-not-exist" >stdin &&
test_must_fail git update-ref -z --stdin <stdin 2>err && test_must_fail git update-ref -z --stdin <stdin 2>err &&
grep "fatal: update $c: invalid <oldvalue>: does-not-exist" err && grep "fatal: update $c: invalid <old-oid>: does-not-exist" err &&
test_must_fail git rev-parse --verify -q $c test_must_fail git rev-parse --verify -q $c
' '
@ -1178,14 +1178,14 @@ test_expect_success 'stdin -z create ref fails with bad new value' '
git update-ref -d "$c" && git update-ref -d "$c" &&
printf $F "create $c" "does-not-exist" >stdin && printf $F "create $c" "does-not-exist" >stdin &&
test_must_fail git update-ref -z --stdin <stdin 2>err && test_must_fail git update-ref -z --stdin <stdin 2>err &&
grep "fatal: create $c: invalid <newvalue>: does-not-exist" err && grep "fatal: create $c: invalid <new-oid>: does-not-exist" err &&
test_must_fail git rev-parse --verify -q $c test_must_fail git rev-parse --verify -q $c
' '
test_expect_success 'stdin -z create ref fails with empty new value' ' test_expect_success 'stdin -z create ref fails with empty new value' '
printf $F "create $c" "" >stdin && printf $F "create $c" "" >stdin &&
test_must_fail git update-ref -z --stdin <stdin 2>err && test_must_fail git update-ref -z --stdin <stdin 2>err &&
grep "fatal: create $c: missing <newvalue>" err && grep "fatal: create $c: missing <new-oid>" err &&
test_must_fail git rev-parse --verify -q $c test_must_fail git rev-parse --verify -q $c
' '
@ -1209,7 +1209,7 @@ test_expect_success 'stdin -z delete ref fails with wrong old value' '
test_expect_success 'stdin -z delete ref fails with zero old value' ' test_expect_success 'stdin -z delete ref fails with zero old value' '
printf $F "delete $a" "$Z" >stdin && printf $F "delete $a" "$Z" >stdin &&
test_must_fail git update-ref -z --stdin <stdin 2>err && test_must_fail git update-ref -z --stdin <stdin 2>err &&
grep "fatal: delete $a: zero <oldvalue>" err && grep "fatal: delete $a: zero <old-oid>" err &&
git rev-parse $m >expect && git rev-parse $m >expect &&
git rev-parse $a >actual && git rev-parse $a >actual &&
test_cmp expect actual test_cmp expect actual