Junio C Hamano | 1290563 | 2005-10-04 16:45:01 -0700 | [diff] [blame] | 1 | git-update-ref(1) |
| 2 | ================= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
Junio C Hamano | c3f0baa | 2007-01-18 15:53:37 -0800 | [diff] [blame] | 6 | git-update-ref - Update the object name stored in a ref safely |
Junio C Hamano | 1290563 | 2005-10-04 16:45:01 -0700 | [diff] [blame] | 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
Martin von Zweigbergk | 7791a1d | 2011-07-01 22:38:26 -0400 | [diff] [blame] | 10 | [verse] |
Elijah Newren | d345e9f | 2018-09-05 10:25:50 -0700 | [diff] [blame] | 11 | 'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<oldvalue>] | [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z]) |
Junio C Hamano | 1290563 | 2005-10-04 16:45:01 -0700 | [diff] [blame] | 12 | |
| 13 | DESCRIPTION |
| 14 | ----------- |
| 15 | Given two arguments, stores the <newvalue> in the <ref>, possibly |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 16 | dereferencing the symbolic refs. E.g. `git update-ref HEAD |
Junio C Hamano | 1290563 | 2005-10-04 16:45:01 -0700 | [diff] [blame] | 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>. |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 22 | E.g. `git update-ref refs/heads/master <newvalue> <oldvalue>` |
Junio C Hamano | 1290563 | 2005-10-04 16:45:01 -0700 | [diff] [blame] | 23 | updates the master branch head to <newvalue> only if its current |
Junio C Hamano | ac5409e | 2006-09-27 01:58:57 -0700 | [diff] [blame] | 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. |
Junio C Hamano | 1290563 | 2005-10-04 16:45:01 -0700 | [diff] [blame] | 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 | |
Sven Verdoolaege | 68db31c | 2007-05-09 12:33:20 +0200 | [diff] [blame] | 40 | If --no-deref is given, <ref> itself is overwritten, rather than |
| 41 | the result of following the symbolic pointers. |
| 42 | |
Junio C Hamano | 1290563 | 2005-10-04 16:45:01 -0700 | [diff] [blame] | 43 | In general, using |
| 44 | |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 45 | git update-ref HEAD "$head" |
Junio C Hamano | 1290563 | 2005-10-04 16:45:01 -0700 | [diff] [blame] | 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 | |
Junio C Hamano | ac5409e | 2006-09-27 01:58:57 -0700 | [diff] [blame] | 58 | With `-d` flag, it deletes the named <ref> after verifying it |
| 59 | still contains <oldvalue>. |
| 60 | |
Brad King | c750ba9 | 2013-09-09 09:22:32 -0400 | [diff] [blame] | 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 |
Patrick Steinhardt | e48cf33 | 2020-04-02 09:10:02 +0200 | [diff] [blame] | 69 | start LF |
| 70 | prepare LF |
| 71 | commit LF |
| 72 | abort LF |
Brad King | c750ba9 | 2013-09-09 09:22:32 -0400 | [diff] [blame] | 73 | |
David Turner | 144c76f | 2015-07-21 17:04:55 -0400 | [diff] [blame] | 74 | With `--create-reflog`, update-ref will create a reflog for each ref |
| 75 | even if one would not ordinarily be created. |
| 76 | |
Brad King | c750ba9 | 2013-09-09 09:22:32 -0400 | [diff] [blame] | 77 | Quote fields containing whitespace as if they were strings in C source |
Michael Haggerty | 1fbd504 | 2014-04-07 15:48:06 +0200 | [diff] [blame] | 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: |
Brad King | c750ba9 | 2013-09-09 09:22:32 -0400 | [diff] [blame] | 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 |
Patrick Steinhardt | e48cf33 | 2020-04-02 09:10:02 +0200 | [diff] [blame] | 90 | start NUL |
| 91 | prepare NUL |
| 92 | commit NUL |
| 93 | abort NUL |
Brad King | c750ba9 | 2013-09-09 09:22:32 -0400 | [diff] [blame] | 94 | |
Michael Haggerty | 1fbd504 | 2014-04-07 15:48:06 +0200 | [diff] [blame] | 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: |
Brad King | c750ba9 | 2013-09-09 09:22:32 -0400 | [diff] [blame] | 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 |
Patrick Steinhardt | faa35ee | 2020-03-30 15:46:20 +0200 | [diff] [blame] | 118 | <oldvalue> is zero or missing, the ref must not exist. |
Brad King | c750ba9 | 2013-09-09 09:22:32 -0400 | [diff] [blame] | 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 | |
Patrick Steinhardt | e48cf33 | 2020-04-02 09:10:02 +0200 | [diff] [blame] | 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 |
| 128 | explicit commit. |
| 129 | |
| 130 | prepare:: |
| 131 | Prepare to commit the transaction. This will create lock files for all |
| 132 | queued reference updates. If one reference could not be locked, the |
| 133 | transaction will be aborted. |
| 134 | |
| 135 | commit:: |
| 136 | Commit all reference updates queued for the transaction, ending the |
| 137 | transaction. |
| 138 | |
| 139 | abort:: |
| 140 | Abort the transaction, releasing all locks if the transaction is in |
| 141 | prepared state. |
| 142 | |
Brad King | c750ba9 | 2013-09-09 09:22:32 -0400 | [diff] [blame] | 143 | If all <ref>s can be locked with matching <oldvalue>s |
| 144 | simultaneously, all modifications are performed. Otherwise, no |
| 145 | modifications are performed. Note that while each individual |
| 146 | <ref> is updated or deleted atomically, a concurrent reader may |
| 147 | still see a subset of the modifications. |
Junio C Hamano | ac5409e | 2006-09-27 01:58:57 -0700 | [diff] [blame] | 148 | |
Nguyễn Thái Ngọc Duy | 76a8788 | 2018-04-30 17:35:33 +0200 | [diff] [blame] | 149 | LOGGING UPDATES |
Shawn Pearce | 6de08ae | 2006-05-17 05:55:40 -0400 | [diff] [blame] | 150 | --------------- |
Bert Wesarg | cd8e371 | 2011-07-11 11:14:18 +0200 | [diff] [blame] | 151 | If config parameter "core.logAllRefUpdates" is true and the ref is one under |
| 152 | "refs/heads/", "refs/remotes/", "refs/notes/", or the symbolic ref HEAD; or |
| 153 | the file "$GIT_DIR/logs/<ref>" exists then `git update-ref` will append |
Shawn Pearce | 6de08ae | 2006-05-17 05:55:40 -0400 | [diff] [blame] | 154 | a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all |
| 155 | symbolic refs before creating the log name) describing the change |
| 156 | in ref value. Log lines are formatted as: |
| 157 | |
Andreas Heiduk | 081d916 | 2018-10-22 22:45:46 +0200 | [diff] [blame] | 158 | oldsha1 SP newsha1 SP committer LF |
| 159 | |
Shawn Pearce | 6de08ae | 2006-05-17 05:55:40 -0400 | [diff] [blame] | 160 | Where "oldsha1" is the 40 character hexadecimal value previously |
| 161 | stored in <ref>, "newsha1" is the 40 character hexadecimal value of |
| 162 | <newvalue> and "committer" is the committer's name, email address |
Thomas Ackermann | 48a8c26 | 2013-01-21 20:16:20 +0100 | [diff] [blame] | 163 | and date in the standard Git committer ident format. |
Shawn Pearce | 6de08ae | 2006-05-17 05:55:40 -0400 | [diff] [blame] | 164 | |
| 165 | Optionally with -m: |
| 166 | |
Andreas Heiduk | 081d916 | 2018-10-22 22:45:46 +0200 | [diff] [blame] | 167 | oldsha1 SP newsha1 SP committer TAB message LF |
| 168 | |
Shawn Pearce | 6de08ae | 2006-05-17 05:55:40 -0400 | [diff] [blame] | 169 | Where all fields are as described above and "message" is the |
| 170 | value supplied to the -m option. |
| 171 | |
| 172 | An update will fail (without changing <ref>) if the current user is |
| 173 | unable to create a new log file, append to the existing log file |
| 174 | or does not have committer information available. |
| 175 | |
Junio C Hamano | 1290563 | 2005-10-04 16:45:01 -0700 | [diff] [blame] | 176 | GIT |
| 177 | --- |
Christian Couder | 9e1f0a8 | 2008-06-06 09:07:32 +0200 | [diff] [blame] | 178 | Part of the linkgit:git[1] suite |