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