man pages section 1: User Commands

Exit Print View

Updated: July 2014

git-update-ref (1)


git-update-ref - Update the object name stored in a ref safely


git update-ref [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] <ref> <newvalue> [<oldvalue>])


Git Manual                                      GIT-UPDATE-REF(1)

     git-update-ref - Update the object name stored in a ref

     git update-ref [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] <ref> <newvalue> [<oldvalue>])

     Given two arguments, stores the <newvalue> in the <ref>,
     possibly dereferencing the symbolic refs. E.g. git
     update-ref HEAD <newvalue> updates the current branch head
     to the new object.

     Given three arguments, stores the <newvalue> in the <ref>,
     possibly dereferencing the symbolic refs, after verifying
     that the current value of the <ref> matches <oldvalue>. E.g.
     git update-ref refs/heads/master <newvalue> <oldvalue>
     updates the master branch head to <newvalue> only if its
     current value is <oldvalue>. You can specify 40 "0" or an
     empty string as <oldvalue> to make sure that the ref you are
     creating does not exist.

     It also allows a "ref" file to be a symbolic pointer to
     another ref file by starting with the four-byte header
     sequence of "ref:".

     More importantly, it allows the update of a ref file to
     follow these symbolic pointers, whether they are symlinks or
     these "regular file symbolic refs". It follows real symlinks
     only if they start with "refs/": otherwise it will just try
     to read them and update them as a regular file (i.e. it will
     allow the filesystem to follow them, but will overwrite such
     a symlink to somewhere else with a regular filename).

     If --no-deref is given, <ref> itself is overwritten, rather
     than the result of following the symbolic pointers.

     In general, using

         git update-ref HEAD "$head"

     should be a lot safer than doing

         echo "$head" > "$GIT_DIR/HEAD"

     both from a symlink following standpoint and an error
     checking standpoint. The "refs/" rule for symlinks means
     that symlinks that point to "outside" the tree are safe:
     they'll be followed for reading but not for writing (so
     we'll never write through a ref symlink to some other tree,
     if you have copied a whole archive by creating a symlink

Git          Last change: 02/22/2012                    1

Git Manual                                      GIT-UPDATE-REF(1)


     With -d flag, it deletes the named <ref> after verifying it
     still contains <oldvalue>.

     If config parameter "core.logAllRefUpdates" is true and the
     ref is one under "refs/heads/", "refs/remotes/",
     "refs/notes/", or the symbolic ref HEAD; or the file
     "$GIT_DIR/logs/<ref>" exists then git update-ref will append
     a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing
     all symbolic refs before creating the log name) describing
     the change in ref value. Log lines are formatted as:

      1. oldsha1 SP newsha1 SP committer LF

         Where "oldsha1" is the 40 character hexadecimal value
         previously stored in <ref>, "newsha1" is the 40
         character hexadecimal value of <newvalue> and
         "committer" is the committer's name, email address and
         date in the standard GIT committer ident format.

     Optionally with -m:

      1. oldsha1 SP newsha1 SP committer TAB message LF

         Where all fields are as described above and "message" is
         the value supplied to the -m option.

     An update will fail (without changing <ref>) if the current
     user is unable to create a new log file, append to the
     existing log file or does not have committer information

     Part of the git(1) suite

     See attributes(5) for descriptions of the following

     |Availability   | developer/versioning/git |
     |Stability      | Uncommitted              |
     This software was built from source available at

Git          Last change: 02/22/2012                    2

Git Manual                                      GIT-UPDATE-REF(1)  The original
     community source was downloaded from  http://git-

     Further information about this software can be found on the
     open source community website at

Git          Last change: 02/22/2012                    3