1GIT-UPDATE-REF(1)                 Git Manual                 GIT-UPDATE-REF(1)
2
3
4

NAME

6       git-update-ref - Update the object name stored in a ref safely
7

SYNOPSIS

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

DESCRIPTION

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
16       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
24       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
27       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
35       If --no-deref is given, <ref> itself is overwritten, rather than the
36       result of following the symbolic pointers.
37
38       In general, using
39
40           git update-ref HEAD "$head"
41
42       should be a lot safer than doing
43
44           echo "$head" > "$GIT_DIR/HEAD"
45
46       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
53       With -d flag, it deletes the named <ref> after verifying it still
54       contains <oldvalue>.
55
56       With --stdin, update-ref reads instructions from standard input and
57       performs all modifications together. Specify commands of the form:
58
59           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
69       With --create-reflog, update-ref will create a reflog for each ref even
70       if one would not ordinarily be created.
71
72       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
77       Alternatively, use -z to specify in NUL-terminated format, without
78       quoting:
79
80           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
90       In this format, use 40 "0" to specify a zero value, and use the empty
91       string to specify a missing value.
92
93       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
97       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
103       create
104           Create <ref> with <newvalue> after verifying it does not exist. The
105           given <newvalue> may not be zero.
106
107       delete
108           Delete <ref> after verifying it exists with <oldvalue>, if given.
109           If given, <oldvalue> may not be zero.
110
111       verify
112           Verify <ref> against <oldvalue> but do not change it. If <oldvalue>
113           is zero or missing, the ref must not exist.
114
115       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
119       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
125       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
130       commit
131           Commit all reference updates queued for the transaction, ending the
132           transaction.
133
134       abort
135           Abort the transaction, releasing all locks if the transaction is in
136           prepared state.
137
138       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

LOGGING UPDATES

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
152           oldsha1 SP newsha1 SP committer LF
153
154       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
159       Optionally with -m:
160
161           oldsha1 SP newsha1 SP committer TAB message LF
162
163       Where all fields are as described above and "message" is the value
164       supplied to the -m option.
165
166       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

GIT

171       Part of the git(1) suite
172
173
174
175Git 2.43.0                        11/20/2023                 GIT-UPDATE-REF(1)
Impressum