blob: 3e737c236074849377e3766c55f4533a270c436f [file] [log] [blame]
Junio C Hamano12905632005-10-04 16:45:01 -07001git-update-ref(1)
2=================
3
4NAME
5----
Junio C Hamanoc3f0baa2007-01-18 15:53:37 -08006git-update-ref - Update the object name stored in a ref safely
Junio C Hamano12905632005-10-04 16:45:01 -07007
8SYNOPSIS
9--------
Martin von Zweigbergk7791a1d2011-07-01 22:38:26 -040010[verse]
Elijah Newrend345e9f2018-09-05 10:25:50 -070011'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<oldvalue>] | [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z])
Junio C Hamano12905632005-10-04 16:45:01 -070012
13DESCRIPTION
14-----------
15Given two arguments, stores the <newvalue> in the <ref>, possibly
Jonathan Niederb1889c32008-06-30 01:09:04 -050016dereferencing the symbolic refs. E.g. `git update-ref HEAD
Junio C Hamano12905632005-10-04 16:45:01 -070017<newvalue>` updates the current branch head to the new object.
18
19Given three arguments, stores the <newvalue> in the <ref>,
20possibly dereferencing the symbolic refs, after verifying that
21the current value of the <ref> matches <oldvalue>.
Jonathan Niederb1889c32008-06-30 01:09:04 -050022E.g. `git update-ref refs/heads/master <newvalue> <oldvalue>`
Junio C Hamano12905632005-10-04 16:45:01 -070023updates the master branch head to <newvalue> only if its current
Junio C Hamanoac5409e2006-09-27 01:58:57 -070024value is <oldvalue>. You can specify 40 "0" or an empty string
25as <oldvalue> to make sure that the ref you are creating does
26not exist.
Junio C Hamano12905632005-10-04 16:45:01 -070027
28It also allows a "ref" file to be a symbolic pointer to another
29ref file by starting with the four-byte header sequence of
30"ref:".
31
32More importantly, it allows the update of a ref file to follow
33these symbolic pointers, whether they are symlinks or these
34"regular file symbolic refs". It follows *real* symlinks only
35if they start with "refs/": otherwise it will just try to read
36them and update them as a regular file (i.e. it will allow the
37filesystem to follow them, but will overwrite such a symlink to
38somewhere else with a regular filename).
39
Sven Verdoolaege68db31c2007-05-09 12:33:20 +020040If --no-deref is given, <ref> itself is overwritten, rather than
41the result of following the symbolic pointers.
42
Junio C Hamano12905632005-10-04 16:45:01 -070043In general, using
44
Jonathan Niederb1889c32008-06-30 01:09:04 -050045 git update-ref HEAD "$head"
Junio C Hamano12905632005-10-04 16:45:01 -070046
47should be a _lot_ safer than doing
48
49 echo "$head" > "$GIT_DIR/HEAD"
50
51both from a symlink following standpoint *and* an error checking
52standpoint. The "refs/" rule for symlinks means that symlinks
53that point to "outside" the tree are safe: they'll be followed
54for reading but not for writing (so we'll never write through a
55ref symlink to some other tree, if you have copied a whole
56archive by creating a symlink tree).
57
Junio C Hamanoac5409e2006-09-27 01:58:57 -070058With `-d` flag, it deletes the named <ref> after verifying it
59still contains <oldvalue>.
60
Brad Kingc750ba92013-09-09 09:22:32 -040061With `--stdin`, update-ref reads instructions from standard input and
62performs 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
Patrick Steinhardte48cf332020-04-02 09:10:02 +020069 start LF
70 prepare LF
71 commit LF
72 abort LF
Brad Kingc750ba92013-09-09 09:22:32 -040073
David Turner144c76f2015-07-21 17:04:55 -040074With `--create-reflog`, update-ref will create a reflog for each ref
75even if one would not ordinarily be created.
76
Brad Kingc750ba92013-09-09 09:22:32 -040077Quote fields containing whitespace as if they were strings in C source
Michael Haggerty1fbd5042014-04-07 15:48:06 +020078code; i.e., surrounded by double-quotes and with backslash escapes.
79Use 40 "0" characters or the empty string to specify a zero value. To
80specify a missing value, omit the value and its preceding SP entirely.
81
82Alternatively, use `-z` to specify in NUL-terminated format, without
83quoting:
Brad Kingc750ba92013-09-09 09:22:32 -040084
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
Patrick Steinhardte48cf332020-04-02 09:10:02 +020090 start NUL
91 prepare NUL
92 commit NUL
93 abort NUL
Brad Kingc750ba92013-09-09 09:22:32 -040094
Michael Haggerty1fbd5042014-04-07 15:48:06 +020095In this format, use 40 "0" to specify a zero value, and use the empty
96string to specify a missing value.
97
98In either format, values can be specified in any form that Git
99recognizes as an object name. Commands in any other format or a
100repeated <ref> produce an error. Command meanings are:
Brad Kingc750ba92013-09-09 09:22:32 -0400101
102update::
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
108create::
109 Create <ref> with <newvalue> after verifying it does not
110 exist. The given <newvalue> may not be zero.
111
112delete::
113 Delete <ref> after verifying it exists with <oldvalue>, if
114 given. If given, <oldvalue> may not be zero.
115
116verify::
117 Verify <ref> against <oldvalue> but do not change it. If
Patrick Steinhardtfaa35ee2020-03-30 15:46:20 +0200118 <oldvalue> is zero or missing, the ref must not exist.
Brad Kingc750ba92013-09-09 09:22:32 -0400119
120option::
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
Patrick Steinhardte48cf332020-04-02 09:10:02 +0200125start::
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
130prepare::
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
135commit::
136 Commit all reference updates queued for the transaction, ending the
137 transaction.
138
139abort::
140 Abort the transaction, releasing all locks if the transaction is in
141 prepared state.
142
Brad Kingc750ba92013-09-09 09:22:32 -0400143If all <ref>s can be locked with matching <oldvalue>s
144simultaneously, all modifications are performed. Otherwise, no
145modifications are performed. Note that while each individual
146<ref> is updated or deleted atomically, a concurrent reader may
147still see a subset of the modifications.
Junio C Hamanoac5409e2006-09-27 01:58:57 -0700148
Nguyễn Thái Ngọc Duy76a87882018-04-30 17:35:33 +0200149LOGGING UPDATES
Shawn Pearce6de08ae2006-05-17 05:55:40 -0400150---------------
Bert Wesargcd8e3712011-07-11 11:14:18 +0200151If 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
153the file "$GIT_DIR/logs/<ref>" exists then `git update-ref` will append
Shawn Pearce6de08ae2006-05-17 05:55:40 -0400154a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all
155symbolic refs before creating the log name) describing the change
156in ref value. Log lines are formatted as:
157
Andreas Heiduk081d9162018-10-22 22:45:46 +0200158 oldsha1 SP newsha1 SP committer LF
159
Shawn Pearce6de08ae2006-05-17 05:55:40 -0400160Where "oldsha1" is the 40 character hexadecimal value previously
161stored in <ref>, "newsha1" is the 40 character hexadecimal value of
162<newvalue> and "committer" is the committer's name, email address
Thomas Ackermann48a8c262013-01-21 20:16:20 +0100163and date in the standard Git committer ident format.
Shawn Pearce6de08ae2006-05-17 05:55:40 -0400164
165Optionally with -m:
166
Andreas Heiduk081d9162018-10-22 22:45:46 +0200167 oldsha1 SP newsha1 SP committer TAB message LF
168
Shawn Pearce6de08ae2006-05-17 05:55:40 -0400169Where all fields are as described above and "message" is the
170value supplied to the -m option.
171
172An update will fail (without changing <ref>) if the current user is
173unable to create a new log file, append to the existing log file
174or does not have committer information available.
175
Junio C Hamano12905632005-10-04 16:45:01 -0700176GIT
177---
Christian Couder9e1f0a82008-06-06 09:07:32 +0200178Part of the linkgit:git[1] suite