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 The final arguments are object names; this command without any options
  29 does not support updating a symbolic ref to point to another ref (see
  30 linkgit:git-symbolic-ref[1]).  But `git update-ref --stdin` does have
  31 the `symref-*` commands so that regular refs and symbolic refs can be
  32 committed in the same transaction.
  33
  34 If --no-deref is given, <ref> itself is overwritten, rather than
  35 the result of following the symbolic pointers.
  36
  37 With `-d`, it deletes the named <ref> after verifying that it
  38 still contains <old-oid>.
  39
  40 With `--stdin`, update-ref reads instructions from standard input and
  41 performs all modifications together.  Specify commands of the form:
  42
  43         update SP <ref> SP <new-oid> [SP <old-oid>] LF
  44         create SP <ref> SP <new-oid> LF
  45         delete SP <ref> [SP <old-oid>] LF
  46         verify SP <ref> [SP <old-oid>] LF
  47         symref-update SP <ref> SP <new-target> [SP (ref SP <old-target> | oid SP <old-oid>)] LF
  48         symref-create SP <ref> SP <new-target> LF
  49         symref-delete SP <ref> [SP <old-target>] LF
  50         symref-verify SP <ref> [SP <old-target>] LF
  51         option SP <opt> LF
  52         start LF
  53         prepare LF
  54         commit LF
  55         abort LF
  56
  57 With `--create-reflog`, update-ref will create a reflog for each ref
  58 even if one would not ordinarily be created.
  59
  60 Quote fields containing whitespace as if they were strings in C source
  61 code; i.e., surrounded by double-quotes and with backslash escapes.
  62 Use 40 "0" characters or the empty string to specify a zero value.  To
  63 specify a missing value, omit the value and its preceding SP entirely.
  64
  65 Alternatively, use `-z` to specify in NUL-terminated format, without
  66 quoting:
  67
  68         update SP <ref> NUL <new-oid> NUL [<old-oid>] NUL
  69         create SP <ref> NUL <new-oid> NUL
  70         delete SP <ref> NUL [<old-oid>] NUL
  71         verify SP <ref> NUL [<old-oid>] NUL
  72         symref-update SP <ref> NUL <new-target> [NUL (ref NUL <old-target> | oid NUL <old-oid>)] NUL
  73         symref-create SP <ref> NUL <new-target> NUL
  74         symref-delete SP <ref> [NUL <old-target>] NUL
  75         symref-verify SP <ref> [NUL <old-target>] NUL
  76         option SP <opt> NUL
  77         start NUL
  78         prepare NUL
  79         commit NUL
  80         abort NUL
  81
  82 In this format, use 40 "0" to specify a zero value, and use the empty
  83 string to specify a missing value.
  84
  85 In either format, values can be specified in any form that Git
  86 recognizes as an object name.  Commands in any other format or a
  87 repeated <ref> produce an error.  Command meanings are:
  88
  89 update::
  90         Set <ref> to <new-oid> after verifying <old-oid>, if given.
  91         Specify a zero <new-oid> to ensure the ref does not exist
  92         after the update and/or a zero <old-oid> to make sure the
  93         ref does not exist before the update.
  94
  95 create::
  96         Create <ref> with <new-oid> after verifying it does not
  97         exist.  The given <new-oid> may not be zero.
  98
  99 delete::
 100         Delete <ref> after verifying it exists with <old-oid>, if
 101         given.  If given, <old-oid> may not be zero.
 102
 103 symref-update::
 104         Set <ref> to <new-target> after verifying <old-target> or <old-oid>,
 105         if given. Specify a zero <old-oid> to ensure that the ref does not
 106         exist before the update.
 107
 108 verify::
 109         Verify <ref> against <old-oid> but do not change it.  If
 110         <old-oid> is zero or missing, the ref must not exist.
 111
 112 symref-create:
 113         Create symbolic ref <ref> with <new-target> after verifying
 114         it does not exist.
 115
 116 symref-delete::
 117         Delete <ref> after verifying it exists with <old-target>, if given.
 118
 119 symref-verify::
 120         Verify symbolic <ref> against <old-target> but do not change it.
 121         If <old-target> is missing, the ref must not exist.  Can only be
 122         used in `no-deref` mode.
 123
 124 option::
 125         Modify the behavior of the next command naming a <ref>.
 126         The only valid option is `no-deref` to avoid dereferencing
 127         a symbolic ref.
 128
 129 start::
 130         Start a transaction. In contrast to a non-transactional session, a
 131         transaction will automatically abort if the session ends without an
 132         explicit commit. This command may create a new empty transaction when
 133         the current one has been committed or aborted already.
 134
 135 prepare::
 136         Prepare to commit the transaction. This will create lock files for all
 137         queued reference updates. If one reference could not be locked, the
 138         transaction will be aborted.
 139
 140 commit::
 141         Commit all reference updates queued for the transaction, ending the
 142         transaction.
 143
 144 abort::
 145         Abort the transaction, releasing all locks if the transaction is in
 146         prepared state.
 147
 148 If all <ref>s can be locked with matching <old-oid>s
 149 simultaneously, all modifications are performed.  Otherwise, no
 150 modifications are performed.  Note that while each individual
 151 <ref> is updated or deleted atomically, a concurrent reader may
 152 still see a subset of the modifications.
 153
 154 LOGGING UPDATES
 155 ---------------
 156 If config parameter "core.logAllRefUpdates" is true and the ref is one
 157 under "refs/heads/", "refs/remotes/", "refs/notes/", or a pseudoref
 158 like HEAD or ORIG_HEAD; or the file "$GIT_DIR/logs/<ref>" exists then
 159 `git update-ref` will append a line to the log file
 160 "$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating
 161 the log name) describing the change in ref value.  Log lines are
 162 formatted as:
 163
 164     oldsha1 SP newsha1 SP committer LF
 165
 166 Where "oldsha1" is the 40 character hexadecimal value previously
 167 stored in <ref>, "newsha1" is the 40 character hexadecimal value of
 168 <new-oid> and "committer" is the committer's name, email address
 169 and date in the standard Git committer ident format.
 170
 171 Optionally with -m:
 172
 173     oldsha1 SP newsha1 SP committer TAB message LF
 174
 175 Where all fields are as described above and "message" is the
 176 value supplied to the -m option.
 177
 178 An update will fail (without changing <ref>) if the current user is
 179 unable to create a new log file, append to the existing log file
 180 or does not have committer information available.
 181
 182 NOTES
 183 -----
 184
 185 Symbolic refs were initially implemented using symbolic links.  This is
 186 now deprecated since not all filesystems support symbolic links.
 187
 188 This command follows *real* symlinks only if they start with "refs/":
 189 otherwise it will just try to read them and update them as a regular
 190 file (i.e. it will allow the filesystem to follow them, but will
 191 overwrite such a symlink to somewhere else with a regular filename).
 192
 193 SEE ALSO
 194 --------
 195 linkgit:git-symbolic-ref[1]
 196
 197 GIT
 198 ---
 199 Part of the linkgit:git[1] suite