1GIT-UPDATE-REF(1) Git Manual GIT-UPDATE-REF(1)
2
6 git-update-ref - Update the object name stored in a ref safely
7
9 git update-ref [-m <reason>] [--no-deref] (-d <ref> [<oldvalue>] | [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z])
10
12 Given two arguments, stores the <newvalue> in the <ref>, possibly
13 dereferencing the symbolic refs. E.g. git update-ref HEAD <newvalue>
14 updates the current branch head to the new object.
15 Given three arguments, stores the <newvalue> in the <ref>, possibly
17 dereferencing the symbolic refs, after verifying that the current value
18 of the <ref> matches <oldvalue>. E.g. git update-ref refs/heads/master
19 <newvalue> <oldvalue> updates the master branch head to <newvalue> only
20 if its current value is <oldvalue>. You can specify 40 "0" or an empty
21 string as <oldvalue> to make sure that the ref you are creating does
22 not exist.
23 It also allows a "ref" file to be a symbolic pointer to another ref
25 file by starting with the four-byte header sequence of "ref:".
26 More importantly, it allows the update of a ref file to follow these
28 symbolic pointers, whether they are symlinks or these "regular file
29 symbolic refs". It follows real symlinks only if they start with
30 "refs/": otherwise it will just try to read them and update them as a
31 regular file (i.e. it will allow the filesystem to follow them, but
32 will overwrite such a symlink to somewhere else with a regular
33 filename).
34 If --no-deref is given, <ref> itself is overwritten, rather than the
36 result of following the symbolic pointers.
37 In general, using
39 git update-ref HEAD "$head"
41 should be a lot safer than doing
43 echo "$head" > "$GIT_DIR/HEAD"
45 both from a symlink following standpoint and an error checking
47 standpoint. The "refs/" rule for symlinks means that symlinks that
48 point to "outside" the tree are safe: they’ll be followed for reading
49 but not for writing (so we’ll never write through a ref symlink to some
50 other tree, if you have copied a whole archive by creating a symlink
51 tree).
52 With -d flag, it deletes the named <ref> after verifying it still
54 contains <oldvalue>.
55 With --stdin, update-ref reads instructions from standard input and
57 performs all modifications together. Specify commands of the form:
58 update SP <ref> SP <newvalue> [SP <oldvalue>] LF
60 create SP <ref> SP <newvalue> LF
61 delete SP <ref> [SP <oldvalue>] LF
62 verify SP <ref> [SP <oldvalue>] LF
63 option SP <opt> LF
64 start LF
65 prepare LF
66 commit LF
67 abort LF
68 With --create-reflog, update-ref will create a reflog for each ref even
70 if one would not ordinarily be created.
71 Quote fields containing whitespace as if they were strings in C source
73 code; i.e., surrounded by double-quotes and with backslash escapes. Use
74 40 "0" characters or the empty string to specify a zero value. To
75 specify a missing value, omit the value and its preceding SP entirely.
76 Alternatively, use -z to specify in NUL-terminated format, without
78 quoting:
79 update SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL
81 create SP <ref> NUL <newvalue> NUL
82 delete SP <ref> NUL [<oldvalue>] NUL
83 verify SP <ref> NUL [<oldvalue>] NUL
84 option SP <opt> NUL
85 start NUL
86 prepare NUL
87 commit NUL
88 abort NUL
89 In this format, use 40 "0" to specify a zero value, and use the empty
91 string to specify a missing value.
92 In either format, values can be specified in any form that Git
94 recognizes as an object name. Commands in any other format or a
95 repeated <ref> produce an error. Command meanings are:
96 update
98 Set <ref> to <newvalue> after verifying <oldvalue>, if given.
99 Specify a zero <newvalue> to ensure the ref does not exist after
100 the update and/or a zero <oldvalue> to make sure the ref does not
101 exist before the update.
102 create
104 Create <ref> with <newvalue> after verifying it does not exist. The
105 given <newvalue> may not be zero.
106 delete
108 Delete <ref> after verifying it exists with <oldvalue>, if given.
109 If given, <oldvalue> may not be zero.
110 verify
112 Verify <ref> against <oldvalue> but do not change it. If <oldvalue>
113 is zero or missing, the ref must not exist.
114 option
116 Modify the behavior of the next command naming a <ref>. The only
117 valid option is no-deref to avoid dereferencing a symbolic ref.
118 start
120 Start a transaction. In contrast to a non-transactional session, a
121 transaction will automatically abort if the session ends without an
122 explicit commit. This command may create a new empty transaction
123 when the current one has been committed or aborted already.
124 prepare
126 Prepare to commit the transaction. This will create lock files for
127 all queued reference updates. If one reference could not be locked,
128 the transaction will be aborted.
129 commit
131 Commit all reference updates queued for the transaction, ending the
132 transaction.
133 abort
135 Abort the transaction, releasing all locks if the transaction is in
136 prepared state.
137 If all <ref>s can be locked with matching <oldvalue>s simultaneously,
139 all modifications are performed. Otherwise, no modifications are
140 performed. Note that while each individual <ref> is updated or deleted
141 atomically, a concurrent reader may still see a subset of the
142 modifications.
143
145 If config parameter "core.logAllRefUpdates" is true and the ref is one
146 under "refs/heads/", "refs/remotes/", "refs/notes/", or a pseudoref
147 like HEAD or ORIG_HEAD; or the file "$GIT_DIR/logs/<ref>" exists then
148 git update-ref will append a line to the log file "$GIT_DIR/logs/<ref>"
149 (dereferencing all symbolic refs before creating the log name)
150 describing the change in ref value. Log lines are formatted as:
151 oldsha1 SP newsha1 SP committer LF
153 Where "oldsha1" is the 40 character hexadecimal value previously stored
155 in <ref>, "newsha1" is the 40 character hexadecimal value of <newvalue>
156 and "committer" is the committer’s name, email address and date in the
157 standard Git committer ident format.
158 Optionally with -m:
160 oldsha1 SP newsha1 SP committer TAB message LF
162 Where all fields are as described above and "message" is the value
164 supplied to the -m option.
165 An update will fail (without changing <ref>) if the current user is
167 unable to create a new log file, append to the existing log file or
168 does not have committer information available.
169
171 Part of the git(1) suite
172Git 2.43.0 11/20/2023 GIT-UPDATE-REF(1)