@matheusbsbs / matheus-bagliano / commits / 67e943c308

update-ref: use {old,new}-oid instead of {old,new}value

The `git-update-ref` command is used to modify references. The usage of {old,new}value in the documentation refers to the OIDs. This is fine since the command only works with regular references which hold OIDs. But if the command is updated to support symrefs, we'd also be dealing with {old,new}-refs. To improve clarity around what exactly {old,new}value mean, let's rename it to {old,new}-oid. Signed-off-by: Karthik Nayak <karthik.188@gmail.com> Acked-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Karthik Nayak committed Apr 2, 2024 at 08:49 UTC 67e943c308d6440b6358531dba67ffba88ec30ae

3 files changed +59 -59

Documentation/git-update-ref.txt

+29 -29

@@ -8,21 +8,21 @@ git-update-ref - Update the object name stored in a ref safely

8 SYNOPSIS

9 --------

10 [verse]

11 -'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<oldvalue>] | [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z])

11 +'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<old-oid>] | [--create-reflog] <ref> <new-oid> [<old-oid>] | --stdin [-z])

13 DESCRIPTION

14 -----------

15 -Given two arguments, stores the <newvalue> in the <ref>, possibly

15 +Given two arguments, stores the <new-oid> in the <ref>, possibly

16 dereferencing the symbolic refs. E.g. `git update-ref HEAD

17 -<newvalue>` updates the current branch head to the new object.

17 +<new-oid>` updates the current branch head to the new object.

19 -Given three arguments, stores the <newvalue> in the <ref>,

19 +Given three arguments, stores the <new-oid> in the <ref>,

20 possibly dereferencing the symbolic refs, after verifying that

21 -the current value of the <ref> matches <oldvalue>.

22 -E.g. `git update-ref refs/heads/master <newvalue> <oldvalue>`

23 -updates the master branch head to <newvalue> only if its current

24 -value is <oldvalue>. You can specify 40 "0" or an empty string

25 -as <oldvalue> to make sure that the ref you are creating does

21 +the current value of the <ref> matches <old-oid>.

22 +E.g. `git update-ref refs/heads/master <new-oid> <old-oid>`

23 +updates the master branch head to <new-oid> only if its current

24 +value is <old-oid>. You can specify 40 "0" or an empty string

25 +as <old-oid> to make sure that the ref you are creating does

26 not exist.

28 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

56 archive by creating a symlink tree).

58 With `-d` flag, it deletes the named <ref> after verifying it

59 -still contains <oldvalue>.

59 +still contains <old-oid>.

61 With `--stdin`, update-ref reads instructions from standard input and

62 performs all modifications together. Specify commands of the form:

64 - update SP <ref> SP <newvalue> [SP <oldvalue>] LF

65 - create SP <ref> SP <newvalue> LF

66 - delete SP <ref> [SP <oldvalue>] LF

67 - verify SP <ref> [SP <oldvalue>] LF

64 + update SP <ref> SP <new-oid> [SP <old-oid>] LF

65 + create SP <ref> SP <new-oid> LF

66 + delete SP <ref> [SP <old-oid>] LF

67 + verify SP <ref> [SP <old-oid>] LF

68 option SP <opt> LF

69 start LF

70 prepare LF

@@ -82,10 +82,10 @@ specify a missing value, omit the value and its preceding SP entirely.

82 Alternatively, use `-z` to specify in NUL-terminated format, without

83 quoting:

85 - update SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL

86 - create SP <ref> NUL <newvalue> NUL

87 - delete SP <ref> NUL [<oldvalue>] NUL

88 - verify SP <ref> NUL [<oldvalue>] NUL

85 + update SP <ref> NUL <new-oid> NUL [<old-oid>] NUL

86 + create SP <ref> NUL <new-oid> NUL

87 + delete SP <ref> NUL [<old-oid>] NUL

88 + verify SP <ref> NUL [<old-oid>] NUL

89 option SP <opt> NUL

90 start NUL

91 prepare NUL

@@ -100,22 +100,22 @@ recognizes as an object name. Commands in any other format or a

100 repeated <ref> produce an error. Command meanings are:

101

102 update::

103 - Set <ref> to <newvalue> after verifying <oldvalue>, if given.

104 - Specify a zero <newvalue> to ensure the ref does not exist

105 - after the update and/or a zero <oldvalue> to make sure the

103 + Set <ref> to <new-oid> after verifying <old-oid>, if given.

104 + Specify a zero <new-oid> to ensure the ref does not exist

105 + after the update and/or a zero <old-oid> to make sure the

106 ref does not exist before the update.

107

108 create::

109 - Create <ref> with <newvalue> after verifying it does not

110 - exist. The given <newvalue> may not be zero.

109 + Create <ref> with <new-oid> after verifying it does not

110 + exist. The given <new-oid> may not be zero.

111

112 delete::

113 - Delete <ref> after verifying it exists with <oldvalue>, if

114 - given. If given, <oldvalue> may not be zero.

113 + Delete <ref> after verifying it exists with <old-oid>, if

114 + given. If given, <old-oid> may not be zero.

115

116 verify::

117 - Verify <ref> against <oldvalue> but do not change it. If

118 - <oldvalue> is zero or missing, the ref must not exist.

117 + Verify <ref> against <old-oid> but do not change it. If

118 + <old-oid> is zero or missing, the ref must not exist.

119

120 option::

121 Modify the behavior of the next command naming a <ref>.

@@ -141,7 +141,7 @@ abort::

141 Abort the transaction, releasing all locks if the transaction is in

142 prepared state.

143

144 -If all <ref>s can be locked with matching <oldvalue>s

144 +If all <ref>s can be locked with matching <old-oid>s

145 simultaneously, all modifications are performed. Otherwise, no

146 modifications are performed. Note that while each individual

147 <ref> is updated or deleted atomically, a concurrent reader may

@@ -161,7 +161,7 @@ formatted as:

161

162 Where "oldsha1" is the 40 character hexadecimal value previously

163 stored in <ref>, "newsha1" is the 40 character hexadecimal value of

164 -<newvalue> and "committer" is the committer's name, email address

164 +<new-oid> and "committer" is the committer's name, email address

165 and date in the standard Git committer ident format.

166

167 Optionally with -m:

builtin/update-ref.c

+13 -13

@@ -9,8 +9,8 @@

9 #include "repository.h"

11 static const char * const git_update_ref_usage[] = {

12 - N_("git update-ref [<options>] -d <refname> [<old-val>]"),

13 - N_("git update-ref [<options>] <refname> <new-val> [<old-val>]"),

12 + N_("git update-ref [<options>] -d <refname> [<old-oid>]"),

13 + N_("git update-ref [<options>] <refname> <new-oid> [<old-oid>]"),

14 N_("git update-ref [<options>] --stdin [-z]"),

15 NULL

16 };

@@ -77,14 +77,14 @@ static char *parse_refname(const char **next)

77 }

79 /*

80 - * The value being parsed is <oldvalue> (as opposed to <newvalue>; the

80 + * The value being parsed is <old-oid> (as opposed to <new-oid>; the

81 * difference affects which error messages are generated):

82 */

83 #define PARSE_SHA1_OLD 0x01

85 /*

86 * For backwards compatibility, accept an empty string for update's

87 - * <newvalue> in binary mode to be equivalent to specifying zeros.

87 + * <new-oid> in binary mode to be equivalent to specifying zeros.

88 */

89 #define PARSE_SHA1_ALLOW_EMPTY 0x02

@@ -140,7 +140,7 @@ static int parse_next_oid(const char **next, const char *end,

140 goto invalid;

141 } else if (flags & PARSE_SHA1_ALLOW_EMPTY) {

142 /* With -z, treat an empty value as all zeros: */

143 - warning("%s %s: missing <newvalue>, treating as zero",

143 + warning("%s %s: missing <new-oid>, treating as zero",

144 command, refname);

145 oidclr(oid);

146 } else {

@@ -158,14 +158,14 @@ static int parse_next_oid(const char **next, const char *end,

158

159 invalid:

160 die(flags & PARSE_SHA1_OLD ?

161 - "%s %s: invalid <oldvalue>: %s" :

162 - "%s %s: invalid <newvalue>: %s",

161 + "%s %s: invalid <old-oid>: %s" :

162 + "%s %s: invalid <new-oid>: %s",

163 command, refname, arg.buf);

164

165 eof:

166 die(flags & PARSE_SHA1_OLD ?

167 - "%s %s: unexpected end of input when reading <oldvalue>" :

168 - "%s %s: unexpected end of input when reading <newvalue>",

167 + "%s %s: unexpected end of input when reading <old-oid>" :

168 + "%s %s: unexpected end of input when reading <new-oid>",

169 command, refname);

170 }

171

@@ -194,7 +194,7 @@ static void parse_cmd_update(struct ref_transaction *transaction,

194

195 if (parse_next_oid(&next, end, &new_oid, "update", refname,

196 PARSE_SHA1_ALLOW_EMPTY))

197 - die("update %s: missing <newvalue>", refname);

197 + die("update %s: missing <new-oid>", refname);

198

199 have_old = !parse_next_oid(&next, end, &old_oid, "update", refname,

200 PARSE_SHA1_OLD);

@@ -225,10 +225,10 @@ static void parse_cmd_create(struct ref_transaction *transaction,

225 die("create: missing <ref>");

226

227 if (parse_next_oid(&next, end, &new_oid, "create", refname, 0))

228 - die("create %s: missing <newvalue>", refname);

228 + die("create %s: missing <new-oid>", refname);

229

230 if (is_null_oid(&new_oid))

231 - die("create %s: zero <newvalue>", refname);

231 + die("create %s: zero <new-oid>", refname);

232

233 if (*next != line_termination)

234 die("create %s: extra input: %s", refname, next);

@@ -260,7 +260,7 @@ static void parse_cmd_delete(struct ref_transaction *transaction,

260 have_old = 0;

261 } else {

262 if (is_null_oid(&old_oid))

263 - die("delete %s: zero <oldvalue>", refname);

263 + die("delete %s: zero <old-oid>", refname);

264 have_old = 1;

265 }

266

t/t1400-update-ref.sh

+17 -17

@@ -622,7 +622,7 @@ test_expect_success 'stdin fails create with no ref' '

622 test_expect_success 'stdin fails create with no new value' '

623 echo "create $a" >stdin &&

624 test_must_fail git update-ref --stdin <stdin 2>err &&

625 - grep "fatal: create $a: missing <newvalue>" err

625 + grep "fatal: create $a: missing <new-oid>" err

626 '

627

628 test_expect_success 'stdin fails create with too many arguments' '

@@ -640,7 +640,7 @@ test_expect_success 'stdin fails update with no ref' '

640 test_expect_success 'stdin fails update with no new value' '

641 echo "update $a" >stdin &&

642 test_must_fail git update-ref --stdin <stdin 2>err &&

643 - grep "fatal: update $a: missing <newvalue>" err

643 + grep "fatal: update $a: missing <new-oid>" err

644 '

645

646 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' '

765 test_expect_success 'stdin update ref fails with bad old value' '

766 echo "update $c $m does-not-exist" >stdin &&

767 test_must_fail git update-ref --stdin <stdin 2>err &&

768 - grep "fatal: update $c: invalid <oldvalue>: does-not-exist" err &&

768 + grep "fatal: update $c: invalid <old-oid>: does-not-exist" err &&

769 test_must_fail git rev-parse --verify -q $c

770 '

771

772 test_expect_success 'stdin create ref fails with bad new value' '

773 echo "create $c does-not-exist" >stdin &&

774 test_must_fail git update-ref --stdin <stdin 2>err &&

775 - grep "fatal: create $c: invalid <newvalue>: does-not-exist" err &&

775 + grep "fatal: create $c: invalid <new-oid>: does-not-exist" err &&

776 test_must_fail git rev-parse --verify -q $c

777 '

778

779 test_expect_success 'stdin create ref fails with zero new value' '

780 echo "create $c " >stdin &&

781 test_must_fail git update-ref --stdin <stdin 2>err &&

782 - grep "fatal: create $c: zero <newvalue>" err &&

782 + grep "fatal: create $c: zero <new-oid>" err &&

783 test_must_fail git rev-parse --verify -q $c

784 '

785

@@ -803,7 +803,7 @@ test_expect_success 'stdin delete ref fails with wrong old value' '

803 test_expect_success 'stdin delete ref fails with zero old value' '

804 echo "delete $a " >stdin &&

805 test_must_fail git update-ref --stdin <stdin 2>err &&

806 - grep "fatal: delete $a: zero <oldvalue>" err &&

806 + grep "fatal: delete $a: zero <old-oid>" err &&

807 git rev-parse $m >expect &&

808 git rev-parse $a >actual &&

809 test_cmp expect actual

@@ -1027,7 +1027,7 @@ test_expect_success 'stdin -z fails create with no ref' '

1027 test_expect_success 'stdin -z fails create with no new value' '

1028 printf $F "create $a" >stdin &&

1029 test_must_fail git update-ref -z --stdin <stdin 2>err &&

1030 - grep "fatal: create $a: unexpected end of input when reading <newvalue>" err

1030 + grep "fatal: create $a: unexpected end of input when reading <new-oid>" err

1031 '

1032

1033 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' '

1045 test_expect_success 'stdin -z fails update with too few args' '

1046 printf $F "update $a" "$m" >stdin &&

1047 test_must_fail git update-ref -z --stdin <stdin 2>err &&

1048 - grep "fatal: update $a: unexpected end of input when reading <oldvalue>" err

1048 + grep "fatal: update $a: unexpected end of input when reading <old-oid>" err

1049 '

1050

1051 test_expect_success 'stdin -z emits warning with empty new value' '

1052 git update-ref $a $m &&

1053 printf $F "update $a" "" "" >stdin &&

1054 git update-ref -z --stdin <stdin 2>err &&

1055 - grep "warning: update $a: missing <newvalue>, treating as zero" err &&

1055 + grep "warning: update $a: missing <new-oid>, treating as zero" err &&

1056 test_must_fail git rev-parse --verify -q $a

1057 '

1058

1059 test_expect_success 'stdin -z fails update with no new value' '

1060 printf $F "update $a" >stdin &&

1061 test_must_fail git update-ref -z --stdin <stdin 2>err &&

1062 - grep "fatal: update $a: unexpected end of input when reading <newvalue>" err

1062 + grep "fatal: update $a: unexpected end of input when reading <new-oid>" err

1063 '

1064

1065 test_expect_success 'stdin -z fails update with no old value' '

1066 printf $F "update $a" "$m" >stdin &&

1067 test_must_fail git update-ref -z --stdin <stdin 2>err &&

1068 - grep "fatal: update $a: unexpected end of input when reading <oldvalue>" err

1068 + grep "fatal: update $a: unexpected end of input when reading <old-oid>" err

1069 '

1070

1071 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' '

1083 test_expect_success 'stdin -z fails delete with no old value' '

1084 printf $F "delete $a" >stdin &&

1085 test_must_fail git update-ref -z --stdin <stdin 2>err &&

1086 - grep "fatal: delete $a: unexpected end of input when reading <oldvalue>" err

1086 + grep "fatal: delete $a: unexpected end of input when reading <old-oid>" err

1087 '

1088

1089 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' '

1101 test_expect_success 'stdin -z fails verify with no old value' '

1102 printf $F "verify $a" >stdin &&

1103 test_must_fail git update-ref -z --stdin <stdin 2>err &&

1104 - grep "fatal: verify $a: unexpected end of input when reading <oldvalue>" err

1104 + grep "fatal: verify $a: unexpected end of input when reading <old-oid>" err

1105 '

1106

1107 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' '

1160 test_expect_success 'stdin -z update ref fails with bad old value' '

1161 printf $F "update $c" "$m" "does-not-exist" >stdin &&

1162 test_must_fail git update-ref -z --stdin <stdin 2>err &&

1163 - grep "fatal: update $c: invalid <oldvalue>: does-not-exist" err &&

1163 + grep "fatal: update $c: invalid <old-oid>: does-not-exist" err &&

1164 test_must_fail git rev-parse --verify -q $c

1165 '

1166

@@ -1178,14 +1178,14 @@ test_expect_success 'stdin -z create ref fails with bad new value' '

1178 git update-ref -d "$c" &&

1179 printf $F "create $c" "does-not-exist" >stdin &&

1180 test_must_fail git update-ref -z --stdin <stdin 2>err &&

1181 - grep "fatal: create $c: invalid <newvalue>: does-not-exist" err &&

1181 + grep "fatal: create $c: invalid <new-oid>: does-not-exist" err &&

1182 test_must_fail git rev-parse --verify -q $c

1183 '

1184

1185 test_expect_success 'stdin -z create ref fails with empty new value' '

1186 printf $F "create $c" "" >stdin &&

1187 test_must_fail git update-ref -z --stdin <stdin 2>err &&

1188 - grep "fatal: create $c: missing <newvalue>" err &&

1188 + grep "fatal: create $c: missing <new-oid>" err &&

1189 test_must_fail git rev-parse --verify -q $c

1190 '

1191

@@ -1209,7 +1209,7 @@ test_expect_success 'stdin -z delete ref fails with wrong old value' '

1209 test_expect_success 'stdin -z delete ref fails with zero old value' '

1210 printf $F "delete $a" "$Z" >stdin &&

1211 test_must_fail git update-ref -z --stdin <stdin 2>err &&

1212 - grep "fatal: delete $a: zero <oldvalue>" err &&

1212 + grep "fatal: delete $a: zero <old-oid>" err &&

1213 git rev-parse $m >expect &&

1214 git rev-parse $a >actual &&

1215 test_cmp expect actual