git-update-ref.txt

   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 [verse]
  11 'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<old-oid>] | [--create-reflog] <ref> <new-oid> [<old-oid>] | --stdin [-z])
  12
  13 DESCRIPTION
  14 -----------
  15 Given two arguments, stores the <new-oid> in the <ref>, possibly
  16 dereferencing the symbolic refs.  E.g. `git update-ref HEAD
  17 <new-oid>` updates the current branch head to the new object.
  18
  19 Given three arguments, stores the <new-oid> in the <ref>,
  20 possibly dereferencing the symbolic refs, after verifying that
  21 the current value of the <ref> matches <old-oid>.
  22 E.g. `git update-ref refs/heads/master <new-oid> <old-oid>`
  23 updates the master branch head to <new-oid> only if its current
  24 value is <old-oid>.  You can specify 40 "0" or an empty string
  25 as <old-oid> to make sure that the ref you are creating does
  26 not exist.
  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
  40 If --no-deref is given, <ref> itself is overwritten, rather than
  41 the result of following the symbolic pointers.
  42
  43 In general, using
  44
  45         git update-ref HEAD "$head"
  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
  58 With `-d` flag, it deletes the named <ref> after verifying it
  59 still contains <old-oid>.
  60
  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 <new-oid> [SP <old-oid>] LF
  65         create SP <ref> SP <new-oid> LF
  66         delete SP <ref> [SP <old-oid>] LF
  67         verify SP <ref> [SP <old-oid>] LF
  68         symref-update SP <ref> SP <new-target> [SP (ref SP <old-target> | oid SP <old-oid>)] LF
  69         symref-create SP <ref> SP <new-target> LF
  70         symref-delete SP <ref> [SP <old-target>] LF
  71         symref-verify SP <ref> [SP <old-target>] LF
  72         option SP <opt> LF
  73         start LF
  74         prepare LF
  75         commit LF
  76         abort LF
  77
  78 With `--create-reflog`, update-ref will create a reflog for each ref
  79 even if one would not ordinarily be created.
  80
  81 Quote fields containing whitespace as if they were strings in C source
  82 code; i.e., surrounded by double-quotes and with backslash escapes.
  83 Use 40 "0" characters or the empty string to specify a zero value.  To
  84 specify a missing value, omit the value and its preceding SP entirely.
  85
  86 Alternatively, use `-z` to specify in NUL-terminated format, without
  87 quoting:
  88
  89         update SP <ref> NUL <new-oid> NUL [<old-oid>] NUL
  90         create SP <ref> NUL <new-oid> NUL
  91         delete SP <ref> NUL [<old-oid>] NUL
  92         verify SP <ref> NUL [<old-oid>] NUL
  93         symref-update SP <ref> NUL <new-target> [NUL (ref NUL <old-target> | oid NUL <old-oid>)] NUL
  94         symref-create SP <ref> NUL <new-target> NUL
  95         symref-delete SP <ref> [NUL <old-target>] NUL
  96         symref-verify SP <ref> [NUL <old-target>] NUL
  97         option SP <opt> NUL
  98         start NUL
  99         prepare NUL
 100         commit NUL
 101         abort NUL
 102
 103 In this format, use 40 "0" to specify a zero value, and use the empty
 104 string to specify a missing value.
 105
 106 In either format, values can be specified in any form that Git
 107 recognizes as an object name.  Commands in any other format or a
 108 repeated <ref> produce an error.  Command meanings are:
 109
 110 update::
 111         Set <ref> to <new-oid> after verifying <old-oid>, if given.
 112         Specify a zero <new-oid> to ensure the ref does not exist
 113         after the update and/or a zero <old-oid> to make sure the
 114         ref does not exist before the update.
 115
 116 create::
 117         Create <ref> with <new-oid> after verifying it does not
 118         exist.  The given <new-oid> may not be zero.
 119
 120 delete::
 121         Delete <ref> after verifying it exists with <old-oid>, if
 122         given.  If given, <old-oid> may not be zero.
 123
 124 symref-update::
 125         Set <ref> to <new-target> after verifying <old-target> or <old-oid>,
 126         if given. Specify a zero <old-oid> to ensure that the ref does not
 127         exist before the update.
 128
 129 verify::
 130         Verify <ref> against <old-oid> but do not change it.  If
 131         <old-oid> is zero or missing, the ref must not exist.
 132
 133 symref-create:
 134         Create symbolic ref <ref> with <new-target> after verifying
 135         it does not exist.
 136
 137 symref-delete::
 138         Delete <ref> after verifying it exists with <old-target>, if given.
 139
 140 symref-verify::
 141         Verify symbolic <ref> against <old-target> but do not change it.
 142         If <old-target> is missing, the ref must not exist.  Can only be
 143         used in `no-deref` mode.
 144
 145 option::
 146         Modify the behavior of the next command naming a <ref>.
 147         The only valid option is `no-deref` to avoid dereferencing
 148         a symbolic ref.
 149
 150 start::
 151         Start a transaction. In contrast to a non-transactional session, a
 152         transaction will automatically abort if the session ends without an
 153         explicit commit. This command may create a new empty transaction when
 154         the current one has been committed or aborted already.
 155
 156 prepare::
 157         Prepare to commit the transaction. This will create lock files for all
 158         queued reference updates. If one reference could not be locked, the
 159         transaction will be aborted.
 160
 161 commit::
 162         Commit all reference updates queued for the transaction, ending the
 163         transaction.
 164
 165 abort::
 166         Abort the transaction, releasing all locks if the transaction is in
 167         prepared state.
 168
 169 If all <ref>s can be locked with matching <old-oid>s
 170 simultaneously, all modifications are performed.  Otherwise, no
 171 modifications are performed.  Note that while each individual
 172 <ref> is updated or deleted atomically, a concurrent reader may
 173 still see a subset of the modifications.
 174
 175 LOGGING UPDATES
 176 ---------------
 177 If config parameter "core.logAllRefUpdates" is true and the ref is one
 178 under "refs/heads/", "refs/remotes/", "refs/notes/", or a pseudoref
 179 like HEAD or ORIG_HEAD; or the file "$GIT_DIR/logs/<ref>" exists then
 180 `git update-ref` will append a line to the log file
 181 "$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating
 182 the log name) describing the change in ref value.  Log lines are
 183 formatted as:
 184
 185     oldsha1 SP newsha1 SP committer LF
 186
 187 Where "oldsha1" is the 40 character hexadecimal value previously
 188 stored in <ref>, "newsha1" is the 40 character hexadecimal value of
 189 <new-oid> and "committer" is the committer's name, email address
 190 and date in the standard Git committer ident format.
 191
 192 Optionally with -m:
 193
 194     oldsha1 SP newsha1 SP committer TAB message LF
 195
 196 Where all fields are as described above and "message" is the
 197 value supplied to the -m option.
 198
 199 An update will fail (without changing <ref>) if the current user is
 200 unable to create a new log file, append to the existing log file
 201 or does not have committer information available.
 202
 203 GIT
 204 ---
 205 Part of the linkgit:git[1] suite