| blob | a1d9e540d4f87f48e0065d2a3add04c013dbb81d |
1 '\" t
2 .\" Title: git-update-ref
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 2024-09-25
6 .\" Manual: Git Manual
7 .\" Source: Git 2.47.0.rc0
8 .\" Language: English
9 .\"
10 .TH "GIT\-UPDATE\-REF" "1" "2024-09-25" "Git 2\&.47\&.0\&.rc0" "Git Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 git-update-ref \- Update the object name stored in a ref safely
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 \fIgit update\-ref\fR [\-m <reason>] [\-\-no\-deref] (\-d <ref> [<old\-oid>] | [\-\-create\-reflog] <ref> <new\-oid> [<old\-oid>] | \-\-stdin [\-z])
36 .fi
37 .SH "DESCRIPTION"
38 .sp
39 Given two arguments, stores the <new\-oid> in the <ref>, possibly dereferencing the symbolic refs\&. E\&.g\&. \fBgit update\-ref HEAD <new\-oid>\fR updates the current branch head to the new object\&.
40 .sp
41 Given three arguments, stores the <new\-oid> in the <ref>, possibly dereferencing the symbolic refs, after verifying that the current value of the <ref> matches <old\-oid>\&. E\&.g\&. \fBgit update\-ref refs/heads/master <new\-oid> <old\-oid>\fR updates the master branch head to <new\-oid> only if its current value is <old\-oid>\&. You can specify 40 "0" or an empty string as <old\-oid> to make sure that the ref you are creating does not exist\&.
42 .sp
43 It also allows a "ref" file to be a symbolic pointer to another ref file by starting with the four\-byte header sequence of "ref:"\&.
44 .sp
45 More importantly, it allows the update of a ref file to follow these symbolic pointers, whether they are symlinks or these "regular file symbolic refs"\&. It follows \fBreal\fR symlinks only if they start with "refs/": otherwise it will just try to read them and update them as a regular file (i\&.e\&. it will allow the filesystem to follow them, but will overwrite such a symlink to somewhere else with a regular filename)\&.
46 .sp
47 If \-\-no\-deref is given, <ref> itself is overwritten, rather than the result of following the symbolic pointers\&.
48 .sp
49 In general, using
50 .sp
51 .if n \{\
52 .RS 4
53 .\}
54 .nf
55 git update\-ref HEAD "$head"
56 .fi
57 .if n \{\
58 .RE
59 .\}
60 .sp
61 should be a \fIlot\fR safer than doing
62 .sp
63 .if n \{\
64 .RS 4
65 .\}
66 .nf
67 echo "$head" > "$GIT_DIR/HEAD"
68 .fi
69 .if n \{\
70 .RE
71 .\}
72 .sp
73 both from a symlink following standpoint \fBand\fR an error checking standpoint\&. The "refs/" rule for symlinks means that symlinks that point to "outside" the tree are safe: they\(cqll be followed for reading but not for writing (so we\(cqll never write through a ref symlink to some other tree, if you have copied a whole archive by creating a symlink tree)\&.
74 .sp
75 With \fB\-d\fR flag, it deletes the named <ref> after verifying it still contains <old\-oid>\&.
76 .sp
77 With \fB\-\-stdin\fR, update\-ref reads instructions from standard input and performs all modifications together\&. Specify commands of the form:
78 .sp
79 .if n \{\
80 .RS 4
81 .\}
82 .nf
83 update SP <ref> SP <new\-oid> [SP <old\-oid>] LF
84 create SP <ref> SP <new\-oid> LF
85 delete SP <ref> [SP <old\-oid>] LF
86 verify SP <ref> [SP <old\-oid>] LF
87 symref\-update SP <ref> SP <new\-target> [SP (ref SP <old\-target> | oid SP <old\-oid>)] LF
88 symref\-create SP <ref> SP <new\-target> LF
89 symref\-delete SP <ref> [SP <old\-target>] LF
90 symref\-verify SP <ref> [SP <old\-target>] LF
91 option SP <opt> LF
92 start LF
93 prepare LF
94 commit LF
95 abort LF
96 .fi
97 .if n \{\
98 .RE
99 .\}
100 .sp
101 With \fB\-\-create\-reflog\fR, update\-ref will create a reflog for each ref even if one would not ordinarily be created\&.
102 .sp
103 Quote fields containing whitespace as if they were strings in C source code; i\&.e\&., surrounded by double\-quotes and with backslash escapes\&. Use 40 "0" characters or the empty string to specify a zero value\&. To specify a missing value, omit the value and its preceding SP entirely\&.
104 .sp
105 Alternatively, use \fB\-z\fR to specify in NUL\-terminated format, without quoting:
106 .sp
107 .if n \{\
108 .RS 4
109 .\}
110 .nf
111 update SP <ref> NUL <new\-oid> NUL [<old\-oid>] NUL
112 create SP <ref> NUL <new\-oid> NUL
113 delete SP <ref> NUL [<old\-oid>] NUL
114 verify SP <ref> NUL [<old\-oid>] NUL
115 symref\-update SP <ref> NUL <new\-target> [NUL (ref NUL <old\-target> | oid NUL <old\-oid>)] NUL
116 symref\-create SP <ref> NUL <new\-target> NUL
117 symref\-delete SP <ref> [NUL <old\-target>] NUL
118 symref\-verify SP <ref> [NUL <old\-target>] NUL
119 option SP <opt> NUL
120 start NUL
121 prepare NUL
122 commit NUL
123 abort NUL
124 .fi
125 .if n \{\
126 .RE
127 .\}
128 .sp
129 In this format, use 40 "0" to specify a zero value, and use the empty string to specify a missing value\&.
130 .sp
131 In either format, values can be specified in any form that Git recognizes as an object name\&. Commands in any other format or a repeated <ref> produce an error\&. Command meanings are:
132 .PP
133 update
134 .RS 4
135 Set <ref> to <new\-oid> after verifying <old\-oid>, if given\&. Specify a zero <new\-oid> to ensure the ref does not exist after the update and/or a zero <old\-oid> to make sure the ref does not exist before the update\&.
136 .RE
137 .PP
138 create
139 .RS 4
140 Create <ref> with <new\-oid> after verifying it does not exist\&. The given <new\-oid> may not be zero\&.
141 .RE
142 .PP
143 delete
144 .RS 4
145 Delete <ref> after verifying it exists with <old\-oid>, if given\&. If given, <old\-oid> may not be zero\&.
146 .RE
147 .PP
148 symref\-update
149 .RS 4
150 Set <ref> to <new\-target> after verifying <old\-target> or <old\-oid>, if given\&. Specify a zero <old\-oid> to ensure that the ref does not exist before the update\&.
151 .RE
152 .PP
153 verify
154 .RS 4
155 Verify <ref> against <old\-oid> but do not change it\&. If <old\-oid> is zero or missing, the ref must not exist\&.
156 .RE
157 .sp
158 symref\-create: Create symbolic ref <ref> with <new\-target> after verifying it does not exist\&.
159 .PP
160 symref\-delete
161 .RS 4
162 Delete <ref> after verifying it exists with <old\-target>, if given\&.
163 .RE
164 .PP
165 symref\-verify
166 .RS 4
167 Verify symbolic <ref> against <old\-target> but do not change it\&. If <old\-target> is missing, the ref must not exist\&. Can only be used in
168 \fBno\-deref\fR
169 mode\&.
170 .RE
171 .PP
172 option
173 .RS 4
174 Modify the behavior of the next command naming a <ref>\&. The only valid option is
175 \fBno\-deref\fR
176 to avoid dereferencing a symbolic ref\&.
177 .RE
178 .PP
179 start
180 .RS 4
181 Start a transaction\&. In contrast to a non\-transactional session, a transaction will automatically abort if the session ends without an explicit commit\&. This command may create a new empty transaction when the current one has been committed or aborted already\&.
182 .RE
183 .PP
184 prepare
185 .RS 4
186 Prepare to commit the transaction\&. This will create lock files for all queued reference updates\&. If one reference could not be locked, the transaction will be aborted\&.
187 .RE
188 .PP
189 commit
190 .RS 4
191 Commit all reference updates queued for the transaction, ending the transaction\&.
192 .RE
193 .PP
194 abort
195 .RS 4
196 Abort the transaction, releasing all locks if the transaction is in prepared state\&.
197 .RE
198 .sp
199 If all <ref>s can be locked with matching <old\-oid>s simultaneously, all modifications are performed\&. Otherwise, no modifications are performed\&. Note that while each individual <ref> is updated or deleted atomically, a concurrent reader may still see a subset of the modifications\&.
200 .SH "LOGGING UPDATES"
201 .sp
202 If config parameter "core\&.logAllRefUpdates" is true and the ref is one under "refs/heads/", "refs/remotes/", "refs/notes/", or a pseudoref like HEAD or ORIG_HEAD; or the file "$GIT_DIR/logs/<ref>" exists then \fBgit update\-ref\fR will append a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating the log name) describing the change in ref value\&. Log lines are formatted as:
203 .sp
204 .if n \{\
205 .RS 4
206 .\}
207 .nf
208 oldsha1 SP newsha1 SP committer LF
209 .fi
210 .if n \{\
211 .RE
212 .\}
213 .sp
214 Where "oldsha1" is the 40 character hexadecimal value previously stored in <ref>, "newsha1" is the 40 character hexadecimal value of <new\-oid> and "committer" is the committer\(cqs name, email address and date in the standard Git committer ident format\&.
215 .sp
216 Optionally with \-m:
217 .sp
218 .if n \{\
219 .RS 4
220 .\}
221 .nf
222 oldsha1 SP newsha1 SP committer TAB message LF
223 .fi
224 .if n \{\
225 .RE
226 .\}
227 .sp
228 Where all fields are as described above and "message" is the value supplied to the \-m option\&.
229 .sp
230 An update will fail (without changing <ref>) if the current user is unable to create a new log file, append to the existing log file or does not have committer information available\&.
231 .SH "GIT"
232 .sp
233 Part of the \fBgit\fR(1) suite