freshlybakedca.ke
Git fork
1git-update-ref(1)
2=================
3
4NAME
5----
6git-update-ref - Update the object name stored in a ref safely
7
8SYNOPSIS
9--------
10[synopsis]
11git update-ref [-m <reason>] [--no-deref] -d <ref> [<old-oid>]
12git update-ref [-m <reason>] [--no-deref] [--create-reflog] <ref> <new-oid> [<old-oid>]
13git update-ref [-m <reason>] [--no-deref] --stdin [-z] [--batch-updates]
14
15DESCRIPTION
16-----------
17Given two arguments, stores the <new-oid> in the <ref>, possibly
18dereferencing the symbolic refs. E.g. `git update-ref HEAD
19<new-oid>` updates the current branch head to the new object.
20
21Given three arguments, stores the <new-oid> in the <ref>,
22possibly dereferencing the symbolic refs, after verifying that
23the current value of the <ref> matches <old-oid>.
24E.g. `git update-ref refs/heads/master <new-oid> <old-oid>`
25updates the master branch head to <new-oid> only if its current
26value is <old-oid>. You can specify 40 "0" or an empty string
27as <old-oid> to make sure that the ref you are creating does
28not exist.
29
30The final arguments are object names; this command without any options
31does not support updating a symbolic ref to point to another ref (see
32linkgit:git-symbolic-ref[1]). But `git update-ref --stdin` does have
33the `symref-*` commands so that regular refs and symbolic refs can be
34committed in the same transaction.
35
36If --no-deref is given, <ref> itself is overwritten, rather than
37the result of following the symbolic pointers.
38
39With `-d`, it deletes the named <ref> after verifying that it
40still contains <old-oid>.
41
42With `--stdin`, update-ref reads instructions from standard input and
43performs all modifications together. Specify commands of the form:
44
45 update SP <ref> SP <new-oid> [SP <old-oid>] LF
46 create SP <ref> SP <new-oid> LF
47 delete SP <ref> [SP <old-oid>] LF
48 verify SP <ref> [SP <old-oid>] LF
49 symref-update SP <ref> SP <new-target> [SP (ref SP <old-target> | oid SP <old-oid>)] LF
50 symref-create SP <ref> SP <new-target> LF
51 symref-delete SP <ref> [SP <old-target>] LF
52 symref-verify SP <ref> [SP <old-target>] LF
53 option SP <opt> LF
54 start LF
55 prepare LF
56 commit LF
57 abort LF
58
59With `--create-reflog`, update-ref will create a reflog for each ref
60even if one would not ordinarily be created.
61
62With `--batch-updates`, update-ref executes the updates in a batch but allows
63individual updates to fail due to invalid or incorrect user input, applying only
64the successful updates. However, system-related errors—such as I/O failures or
65memory issues—will result in a full failure of all batched updates. Any failed
66updates will be reported in the following format:
67
68 rejected SP (<old-oid> | <old-target>) SP (<new-oid> | <new-target>) SP <rejection-reason> LF
69
70Quote fields containing whitespace as if they were strings in C source
71code; i.e., surrounded by double-quotes and with backslash escapes.
72Use 40 "0" characters or the empty string to specify a zero value. To
73specify a missing value, omit the value and its preceding SP entirely.
74
75Alternatively, use `-z` to specify in NUL-terminated format, without
76quoting:
77
78 update SP <ref> NUL <new-oid> NUL [<old-oid>] NUL
79 create SP <ref> NUL <new-oid> NUL
80 delete SP <ref> NUL [<old-oid>] NUL
81 verify SP <ref> NUL [<old-oid>] NUL
82 symref-update SP <ref> NUL <new-target> [NUL (ref NUL <old-target> | oid NUL <old-oid>)] NUL
83 symref-create SP <ref> NUL <new-target> NUL
84 symref-delete SP <ref> [NUL <old-target>] NUL
85 symref-verify SP <ref> [NUL <old-target>] NUL
86 option SP <opt> NUL
87 start NUL
88 prepare NUL
89 commit NUL
90 abort NUL
91
92In this format, use 40 "0" to specify a zero value, and use the empty
93string to specify a missing value.
94
95In either format, values can be specified in any form that Git
96recognizes as an object name. Commands in any other format or a
97repeated <ref> produce an error. Command meanings are:
98
99update::
100 Set <ref> to <new-oid> after verifying <old-oid>, if given.
101 Specify a zero <new-oid> to ensure the ref does not exist
102 after the update and/or a zero <old-oid> to make sure the
103 ref does not exist before the update.
104
105create::
106 Create <ref> with <new-oid> after verifying that it does not
107 exist. The given <new-oid> may not be zero.
108
109delete::
110 Delete <ref> after verifying that it exists with <old-oid>, if
111 given. If given, <old-oid> may not be zero.
112
113symref-update::
114 Set <ref> to <new-target> after verifying <old-target> or <old-oid>,
115 if given. Specify a zero <old-oid> to ensure that the ref does not
116 exist before the update.
117
118verify::
119 Verify <ref> against <old-oid> but do not change it. If
120 <old-oid> is zero or missing, the ref must not exist.
121
122symref-create:
123 Create symbolic ref <ref> with <new-target> after verifying that
124 it does not exist.
125
126symref-delete::
127 Delete <ref> after verifying that it exists with <old-target>, if given.
128
129symref-verify::
130 Verify symbolic <ref> against <old-target> but do not change it.
131 If <old-target> is missing, the ref must not exist. Can only be
132 used in `no-deref` mode.
133
134option::
135 Modify the behavior of the next command naming a <ref>.
136 The only valid option is `no-deref` to avoid dereferencing
137 a symbolic ref.
138
139start::
140 Start a transaction. In contrast to a non-transactional session, a
141 transaction will automatically abort if the session ends without an
142 explicit commit. This command may create a new empty transaction when
143 the current one has been committed or aborted already.
144
145prepare::
146 Prepare to commit the transaction. This will create lock files for all
147 queued reference updates. If one reference could not be locked, the
148 transaction will be aborted.
149
150commit::
151 Commit all reference updates queued for the transaction, ending the
152 transaction.
153
154abort::
155 Abort the transaction, releasing all locks if the transaction is in
156 prepared state.
157
158If all <ref>s can be locked with matching <old-oid>s
159simultaneously, all modifications are performed. Otherwise, no
160modifications are performed. Note that while each individual
161<ref> is updated or deleted atomically, a concurrent reader may
162still see a subset of the modifications.
163
164LOGGING UPDATES
165---------------
166If config parameter "core.logAllRefUpdates" is true and the ref is one
167under "refs/heads/", "refs/remotes/", "refs/notes/", or a pseudoref
168like HEAD or ORIG_HEAD; or the file "$GIT_DIR/logs/<ref>" exists then
169`git update-ref` will append a line to the log file
170"$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating
171the log name) describing the change in ref value. Log lines are
172formatted as:
173
174 oldsha1 SP newsha1 SP committer LF
175
176Where "oldsha1" is the 40 character hexadecimal value previously
177stored in <ref>, "newsha1" is the 40 character hexadecimal value of
178<new-oid> and "committer" is the committer's name, email address
179and date in the standard Git committer ident format.
180
181Optionally with -m:
182
183 oldsha1 SP newsha1 SP committer TAB message LF
184
185Where all fields are as described above and "message" is the
186value supplied to the -m option.
187
188An update will fail (without changing <ref>) if the current user is
189unable to create a new log file, append to the existing log file
190or does not have committer information available.
191
192NOTES
193-----
194
195Symbolic refs were initially implemented using symbolic links. This is
196now deprecated since not all filesystems support symbolic links.
197
198This command follows *real* symlinks only if they start with "refs/":
199otherwise it will just try to read them and update them as a regular
200file (i.e. it will allow the filesystem to follow them, but will
201overwrite such a symlink to somewhere else with a regular filename).
202
203SEE ALSO
204--------
205linkgit:git-symbolic-ref[1]
206
207GIT
208---
209Part of the linkgit:git[1] suite