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
 152 under "refs/heads/", "refs/remotes/", "refs/notes/", or a pseudoref
 153 like HEAD or ORIG_HEAD; or the file "$GIT_DIR/logs/<ref>" exists then
 154 `git update-ref` will append a line to the log file
 155 "$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating
 156 the log name) describing the change in ref value.  Log lines are
 157 formatted as:
 158
 159     oldsha1 SP newsha1 SP committer LF
 160
 161 Where "oldsha1" is the 40 character hexadecimal value previously
 162 stored in <ref>, "newsha1" is the 40 character hexadecimal value of
 163 <newvalue> and "committer" is the committer's name, email address
 164 and date in the standard Git committer ident format.
 165
 166 Optionally with -m:
 167
 168     oldsha1 SP newsha1 SP committer TAB message LF
 169
 170 Where all fields are as described above and "message" is the
 171 value supplied to the -m option.
 172
 173 An update will fail (without changing <ref>) if the current user is
 174 unable to create a new log file, append to the existing log file
 175 or does not have committer information available.
 176
 177 GIT
 178 ---
 179 Part of the linkgit:git[1] suite