Documentation/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> [<oldvalue>] | [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z])
  12
  13 DESCRIPTION
  14 -----------
  15 Given two arguments, stores the <newvalue> in the <ref>, possibly
  16 dereferencing the symbolic refs.  E.g. `git update-ref HEAD
  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>.
  22 E.g. `git update-ref refs/heads/master <newvalue> <oldvalue>`
  23 updates the master branch head to <newvalue> only if its current
  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.
  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 <oldvalue>.
  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 <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         start LF
  70         prepare LF
  71         commit LF
  72         abort LF
  73
  74 With `--create-reflog`, update-ref will create a reflog for each ref
  75 even if one would not ordinarily be created.
  76
  77 Quote fields containing whitespace as if they were strings in C source
  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:
  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
  90         start NUL
  91         prepare NUL
  92         commit NUL
  93         abort NUL
  94
  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:
 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
 118         <oldvalue> is zero or missing, the ref must not exist.
 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
 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. This command may create a new empty transaction when
 129         the current one has been committed or aborted already.
 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
 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.
 149
 150 LOGGING UPDATES
 151 ---------------
 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:
 159
 160     oldsha1 SP newsha1 SP committer LF
 161
 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
 165 and date in the standard Git committer ident format.
 166
 167 Optionally with -m:
 168
 169     oldsha1 SP newsha1 SP committer TAB message LF
 170
 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
 178 GIT
 179 ---
 180 Part of the linkgit:git[1] suite