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.
 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
 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.
 148
 149 LOGGING UPDATES
 150 ---------------
 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
 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
 158     oldsha1 SP newsha1 SP committer LF
 159
 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
 163 and date in the standard Git committer ident format.
 164
 165 Optionally with -m:
 166
 167     oldsha1 SP newsha1 SP committer TAB message LF
 168
 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
 176 GIT
 177 ---
 178 Part of the linkgit:git[1] suite