]>
Commit | Line | Data |
---|---|---|
12905637 JH |
1 | git-update-ref(1) |
2 | ================= | |
3 | ||
4 | NAME | |
5 | ---- | |
c3f0baac | 6 | git-update-ref - Update the object name stored in a ref safely |
12905637 JH |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
7791a1d9 | 10 | [verse] |
d345e9fb | 11 | 'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<oldvalue>] | [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z]) |
12905637 JH |
12 | |
13 | DESCRIPTION | |
14 | ----------- | |
15 | Given two arguments, stores the <newvalue> in the <ref>, possibly | |
b1889c36 | 16 | dereferencing the symbolic refs. E.g. `git update-ref HEAD |
12905637 JH |
17 | <newvalue>` updates the current branch head to the new object. |
18 | ||
19 | Given three arguments, stores the <newvalue> in the <ref>, | |
20 | possibly dereferencing the symbolic refs, after verifying that | |
21 | the current value of the <ref> matches <oldvalue>. | |
b1889c36 | 22 | E.g. `git update-ref refs/heads/master <newvalue> <oldvalue>` |
12905637 | 23 | updates the master branch head to <newvalue> only if its current |
ac5409e4 JH |
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 | |
26 | not exist. | |
12905637 JH |
27 | |
28 | It also allows a "ref" file to be a symbolic pointer to another | |
29 | ref file by starting with the four-byte header sequence of | |
30 | "ref:". | |
31 | ||
32 | More importantly, it allows the update of a ref file to follow | |
33 | these symbolic pointers, whether they are symlinks or these | |
34 | "regular file symbolic refs". It follows *real* symlinks only | |
35 | if they start with "refs/": otherwise it will just try to read | |
36 | them and update them as a regular file (i.e. it will allow the | |
37 | filesystem to follow them, but will overwrite such a symlink to | |
38 | somewhere else with a regular filename). | |
39 | ||
68db31cc SV |
40 | If --no-deref is given, <ref> itself is overwritten, rather than |
41 | the result of following the symbolic pointers. | |
42 | ||
12905637 JH |
43 | In general, using |
44 | ||
b1889c36 | 45 | git update-ref HEAD "$head" |
12905637 JH |
46 | |
47 | should be a _lot_ safer than doing | |
48 | ||
49 | echo "$head" > "$GIT_DIR/HEAD" | |
50 | ||
51 | both from a symlink following standpoint *and* an error checking | |
52 | standpoint. The "refs/" rule for symlinks means that symlinks | |
53 | that point to "outside" the tree are safe: they'll be followed | |
54 | for reading but not for writing (so we'll never write through a | |
55 | ref symlink to some other tree, if you have copied a whole | |
56 | archive by creating a symlink tree). | |
57 | ||
ac5409e4 JH |
58 | With `-d` flag, it deletes the named <ref> after verifying it |
59 | still contains <oldvalue>. | |
60 | ||
c750ba95 BK |
61 | With `--stdin`, update-ref reads instructions from standard input and |
62 | performs all modifications together. Specify commands of the form: | |
63 | ||
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 | |
68 | option SP <opt> LF | |
e48cf33b PS |
69 | start LF |
70 | prepare LF | |
71 | commit LF | |
72 | abort LF | |
c750ba95 | 73 | |
144c76fa DT |
74 | With `--create-reflog`, update-ref will create a reflog for each ref |
75 | even if one would not ordinarily be created. | |
76 | ||
c750ba95 | 77 | Quote fields containing whitespace as if they were strings in C source |
1fbd5049 MH |
78 | code; i.e., surrounded by double-quotes and with backslash escapes. |
79 | Use 40 "0" characters or the empty string to specify a zero value. To | |
80 | specify a missing value, omit the value and its preceding SP entirely. | |
81 | ||
82 | Alternatively, use `-z` to specify in NUL-terminated format, without | |
83 | quoting: | |
c750ba95 BK |
84 | |
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 | |
89 | option SP <opt> NUL | |
e48cf33b PS |
90 | start NUL |
91 | prepare NUL | |
92 | commit NUL | |
93 | abort NUL | |
c750ba95 | 94 | |
1fbd5049 MH |
95 | In this format, use 40 "0" to specify a zero value, and use the empty |
96 | string to specify a missing value. | |
97 | ||
98 | In either format, values can be specified in any form that Git | |
99 | recognizes as an object name. Commands in any other format or a | |
100 | repeated <ref> produce an error. Command meanings are: | |
c750ba95 BK |
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 | |
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. | |
111 | ||
112 | delete:: | |
113 | Delete <ref> after verifying it exists with <oldvalue>, if | |
114 | given. If given, <oldvalue> may not be zero. | |
115 | ||
116 | verify:: | |
117 | Verify <ref> against <oldvalue> but do not change it. If | |
faa35eec | 118 | <oldvalue> is zero or missing, the ref must not exist. |
c750ba95 BK |
119 | |
120 | option:: | |
121 | Modify behavior of the next command naming a <ref>. | |
122 | The only valid option is `no-deref` to avoid dereferencing | |
123 | a symbolic ref. | |
124 | ||
e48cf33b PS |
125 | start:: |
126 | Start a transaction. In contrast to a non-transactional session, a | |
127 | transaction will automatically abort if the session ends without an | |
262a4d28 PS |
128 | explicit commit. This command may create a new empty transaction when |
129 | the current one has been committed or aborted already. | |
e48cf33b PS |
130 | |
131 | prepare:: | |
132 | Prepare to commit the transaction. This will create lock files for all | |
133 | queued reference updates. If one reference could not be locked, the | |
134 | transaction will be aborted. | |
135 | ||
136 | commit:: | |
137 | Commit all reference updates queued for the transaction, ending the | |
138 | transaction. | |
139 | ||
140 | abort:: | |
141 | Abort the transaction, releasing all locks if the transaction is in | |
142 | prepared state. | |
143 | ||
c750ba95 BK |
144 | If all <ref>s can be locked with matching <oldvalue>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 | |
148 | still see a subset of the modifications. | |
ac5409e4 | 149 | |
76a8788c | 150 | LOGGING UPDATES |
6de08ae6 | 151 | --------------- |
09743417 HWN |
152 | If config parameter "core.logAllRefUpdates" is true and the ref is one |
153 | under "refs/heads/", "refs/remotes/", "refs/notes/", or a pseudoref | |
154 | like HEAD or ORIG_HEAD; or the file "$GIT_DIR/logs/<ref>" exists then | |
155 | `git update-ref` will append a line to the log file | |
156 | "$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating | |
157 | the log name) describing the change in ref value. Log lines are | |
158 | formatted as: | |
6de08ae6 | 159 | |
081d9161 AH |
160 | oldsha1 SP newsha1 SP committer LF |
161 | ||
6de08ae6 SP |
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 | |
48a8c26c | 165 | and date in the standard Git committer ident format. |
6de08ae6 SP |
166 | |
167 | Optionally with -m: | |
168 | ||
081d9161 AH |
169 | oldsha1 SP newsha1 SP committer TAB message LF |
170 | ||
6de08ae6 SP |
171 | Where all fields are as described above and "message" is the |
172 | value supplied to the -m option. | |
173 | ||
174 | An update will fail (without changing <ref>) if the current user is | |
175 | unable to create a new log file, append to the existing log file | |
176 | or does not have committer information available. | |
177 | ||
12905637 JH |
178 | GIT |
179 | --- | |
9e1f0a85 | 180 | Part of the linkgit:git[1] suite |