]>
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] |
144c76fa | 11 | 'git update-ref' [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] [--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 | |
69 | ||
144c76fa DT |
70 | With `--create-reflog`, update-ref will create a reflog for each ref |
71 | even if one would not ordinarily be created. | |
72 | ||
c750ba95 | 73 | Quote fields containing whitespace as if they were strings in C source |
1fbd5049 MH |
74 | code; i.e., surrounded by double-quotes and with backslash escapes. |
75 | Use 40 "0" characters or the empty string to specify a zero value. To | |
76 | specify a missing value, omit the value and its preceding SP entirely. | |
77 | ||
78 | Alternatively, use `-z` to specify in NUL-terminated format, without | |
79 | quoting: | |
c750ba95 BK |
80 | |
81 | update SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL | |
82 | create SP <ref> NUL <newvalue> NUL | |
83 | delete SP <ref> NUL [<oldvalue>] NUL | |
84 | verify SP <ref> NUL [<oldvalue>] NUL | |
85 | option SP <opt> NUL | |
86 | ||
1fbd5049 MH |
87 | In this format, use 40 "0" to specify a zero value, and use the empty |
88 | string to specify a missing value. | |
89 | ||
90 | In either format, values can be specified in any form that Git | |
91 | recognizes as an object name. Commands in any other format or a | |
92 | repeated <ref> produce an error. Command meanings are: | |
c750ba95 BK |
93 | |
94 | update:: | |
95 | Set <ref> to <newvalue> after verifying <oldvalue>, if given. | |
96 | Specify a zero <newvalue> to ensure the ref does not exist | |
97 | after the update and/or a zero <oldvalue> to make sure the | |
98 | ref does not exist before the update. | |
99 | ||
100 | create:: | |
101 | Create <ref> with <newvalue> after verifying it does not | |
102 | exist. The given <newvalue> may not be zero. | |
103 | ||
104 | delete:: | |
105 | Delete <ref> after verifying it exists with <oldvalue>, if | |
106 | given. If given, <oldvalue> may not be zero. | |
107 | ||
108 | verify:: | |
109 | Verify <ref> against <oldvalue> but do not change it. If | |
110 | <oldvalue> zero or missing, the ref must not exist. | |
111 | ||
112 | option:: | |
113 | Modify behavior of the next command naming a <ref>. | |
114 | The only valid option is `no-deref` to avoid dereferencing | |
115 | a symbolic ref. | |
116 | ||
c750ba95 BK |
117 | If all <ref>s can be locked with matching <oldvalue>s |
118 | simultaneously, all modifications are performed. Otherwise, no | |
119 | modifications are performed. Note that while each individual | |
120 | <ref> is updated or deleted atomically, a concurrent reader may | |
121 | still see a subset of the modifications. | |
ac5409e4 | 122 | |
6de08ae6 SP |
123 | Logging Updates |
124 | --------------- | |
cd8e3711 BW |
125 | If config parameter "core.logAllRefUpdates" is true and the ref is one under |
126 | "refs/heads/", "refs/remotes/", "refs/notes/", or the symbolic ref HEAD; or | |
127 | the file "$GIT_DIR/logs/<ref>" exists then `git update-ref` will append | |
6de08ae6 SP |
128 | a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all |
129 | symbolic refs before creating the log name) describing the change | |
130 | in ref value. Log lines are formatted as: | |
131 | ||
132 | . oldsha1 SP newsha1 SP committer LF | |
133 | + | |
134 | Where "oldsha1" is the 40 character hexadecimal value previously | |
135 | stored in <ref>, "newsha1" is the 40 character hexadecimal value of | |
136 | <newvalue> and "committer" is the committer's name, email address | |
48a8c26c | 137 | and date in the standard Git committer ident format. |
6de08ae6 SP |
138 | |
139 | Optionally with -m: | |
140 | ||
141 | . oldsha1 SP newsha1 SP committer TAB message LF | |
142 | + | |
143 | Where all fields are as described above and "message" is the | |
144 | value supplied to the -m option. | |
145 | ||
146 | An update will fail (without changing <ref>) if the current user is | |
147 | unable to create a new log file, append to the existing log file | |
148 | or does not have committer information available. | |
149 | ||
12905637 JH |
150 | GIT |
151 | --- | |
9e1f0a85 | 152 | Part of the linkgit:git[1] suite |