man1/git-update-ref.1

   1 '\" t
   2 .\"     Title: git-update-ref
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-09-10
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.46.0.551.gc5ee8f2d1c
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-UPDATE\-REF" "1" "2024-09-10" "Git 2\&.46\&.0\&.551\&.gc5ee8f" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-update-ref \- Update the object name stored in a ref safely
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit update\-ref\fR [\-m <reason>] [\-\-no\-deref] (\-d <ref> [<old\-oid>] | [\-\-create\-reflog] <ref> <new\-oid> [<old\-oid>] | \-\-stdin [\-z])
  36 .fi
  37 .SH "DESCRIPTION"
  38 .sp
  39 Given two arguments, stores the <new\-oid> in the <ref>, possibly dereferencing the symbolic refs\&. E\&.g\&. \fBgit update\-ref HEAD <new\-oid>\fR updates the current branch head to the new object\&.
  40 .sp
  41 Given three arguments, stores the <new\-oid> in the <ref>, possibly dereferencing the symbolic refs, after verifying that the current value of the <ref> matches <old\-oid>\&. E\&.g\&. \fBgit update\-ref refs/heads/master <new\-oid> <old\-oid>\fR updates the master branch head to <new\-oid> only if its current value is <old\-oid>\&. You can specify 40 "0" or an empty string as <old\-oid> to make sure that the ref you are creating does not exist\&.
  42 .sp
  43 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:"\&.
  44 .sp
  45 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 \fBreal\fR 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)\&.
  46 .sp
  47 If \-\-no\-deref is given, <ref> itself is overwritten, rather than the result of following the symbolic pointers\&.
  48 .sp
  49 In general, using
  50 .sp
  51 .if n \{\
  52 .RS 4
  53 .\}
  54 .nf
  55 git update\-ref HEAD "$head"
  56 .fi
  57 .if n \{\
  58 .RE
  59 .\}
  60 .sp
  61 should be a \fIlot\fR safer than doing
  62 .sp
  63 .if n \{\
  64 .RS 4
  65 .\}
  66 .nf
  67 echo "$head" > "$GIT_DIR/HEAD"
  68 .fi
  69 .if n \{\
  70 .RE
  71 .\}
  72 .sp
  73 both from a symlink following standpoint \fBand\fR an error checking standpoint\&. The "refs/" rule for symlinks means that symlinks that point to "outside" the tree are safe: they\(cqll be followed for reading but not for writing (so we\(cqll never write through a ref symlink to some other tree, if you have copied a whole archive by creating a symlink tree)\&.
  74 .sp
  75 With \fB\-d\fR flag, it deletes the named <ref> after verifying it still contains <old\-oid>\&.
  76 .sp
  77 With \fB\-\-stdin\fR, update\-ref reads instructions from standard input and performs all modifications together\&. Specify commands of the form:
  78 .sp
  79 .if n \{\
  80 .RS 4
  81 .\}
  82 .nf
  83 update SP <ref> SP <new\-oid> [SP <old\-oid>] LF
  84 create SP <ref> SP <new\-oid> LF
  85 delete SP <ref> [SP <old\-oid>] LF
  86 verify SP <ref> [SP <old\-oid>] LF
  87 symref\-update SP <ref> SP <new\-target> [SP (ref SP <old\-target> | oid SP <old\-oid>)] LF
  88 symref\-create SP <ref> SP <new\-target> LF
  89 symref\-delete SP <ref> [SP <old\-target>] LF
  90 symref\-verify SP <ref> [SP <old\-target>] LF
  91 option SP <opt> LF
  92 start LF
  93 prepare LF
  94 commit LF
  95 abort LF
  96 .fi
  97 .if n \{\
  98 .RE
  99 .\}
 100 .sp
 101 With \fB\-\-create\-reflog\fR, update\-ref will create a reflog for each ref even if one would not ordinarily be created\&.
 102 .sp
 103 Quote fields containing whitespace as if they were strings in C source code; i\&.e\&., surrounded by double\-quotes and with backslash escapes\&. Use 40 "0" characters or the empty string to specify a zero value\&. To specify a missing value, omit the value and its preceding SP entirely\&.
 104 .sp
 105 Alternatively, use \fB\-z\fR to specify in NUL\-terminated format, without quoting:
 106 .sp
 107 .if n \{\
 108 .RS 4
 109 .\}
 110 .nf
 111 update SP <ref> NUL <new\-oid> NUL [<old\-oid>] NUL
 112 create SP <ref> NUL <new\-oid> NUL
 113 delete SP <ref> NUL [<old\-oid>] NUL
 114 verify SP <ref> NUL [<old\-oid>] NUL
 115 symref\-update SP <ref> NUL <new\-target> [NUL (ref NUL <old\-target> | oid NUL <old\-oid>)] NUL
 116 symref\-create SP <ref> NUL <new\-target> NUL
 117 symref\-delete SP <ref> [NUL <old\-target>] NUL
 118 symref\-verify SP <ref> [NUL <old\-target>] NUL
 119 option SP <opt> NUL
 120 start NUL
 121 prepare NUL
 122 commit NUL
 123 abort NUL
 124 .fi
 125 .if n \{\
 126 .RE
 127 .\}
 128 .sp
 129 In this format, use 40 "0" to specify a zero value, and use the empty string to specify a missing value\&.
 130 .sp
 131 In either format, values can be specified in any form that Git recognizes as an object name\&. Commands in any other format or a repeated <ref> produce an error\&. Command meanings are:
 132 .PP
 133 update
 134 .RS 4
 135 Set <ref> to <new\-oid> after verifying <old\-oid>, if given\&. Specify a zero <new\-oid> to ensure the ref does not exist after the update and/or a zero <old\-oid> to make sure the ref does not exist before the update\&.
 136 .RE
 137 .PP
 138 create
 139 .RS 4
 140 Create <ref> with <new\-oid> after verifying it does not exist\&. The given <new\-oid> may not be zero\&.
 141 .RE
 142 .PP
 143 delete
 144 .RS 4
 145 Delete <ref> after verifying it exists with <old\-oid>, if given\&. If given, <old\-oid> may not be zero\&.
 146 .RE
 147 .PP
 148 symref\-update
 149 .RS 4
 150 Set <ref> to <new\-target> after verifying <old\-target> or <old\-oid>, if given\&. Specify a zero <old\-oid> to ensure that the ref does not exist before the update\&.
 151 .RE
 152 .PP
 153 verify
 154 .RS 4
 155 Verify <ref> against <old\-oid> but do not change it\&. If <old\-oid> is zero or missing, the ref must not exist\&.
 156 .RE
 157 .sp
 158 symref\-create: Create symbolic ref <ref> with <new\-target> after verifying it does not exist\&.
 159 .PP
 160 symref\-delete
 161 .RS 4
 162 Delete <ref> after verifying it exists with <old\-target>, if given\&.
 163 .RE
 164 .PP
 165 symref\-verify
 166 .RS 4
 167 Verify symbolic <ref> against <old\-target> but do not change it\&. If <old\-target> is missing, the ref must not exist\&. Can only be used in
 168 \fBno\-deref\fR
 169 mode\&.
 170 .RE
 171 .PP
 172 option
 173 .RS 4
 174 Modify the behavior of the next command naming a <ref>\&. The only valid option is
 175 \fBno\-deref\fR
 176 to avoid dereferencing a symbolic ref\&.
 177 .RE
 178 .PP
 179 start
 180 .RS 4
 181 Start a transaction\&. In contrast to a non\-transactional session, a transaction will automatically abort if the session ends without an explicit commit\&. This command may create a new empty transaction when the current one has been committed or aborted already\&.
 182 .RE
 183 .PP
 184 prepare
 185 .RS 4
 186 Prepare to commit the transaction\&. This will create lock files for all queued reference updates\&. If one reference could not be locked, the transaction will be aborted\&.
 187 .RE
 188 .PP
 189 commit
 190 .RS 4
 191 Commit all reference updates queued for the transaction, ending the transaction\&.
 192 .RE
 193 .PP
 194 abort
 195 .RS 4
 196 Abort the transaction, releasing all locks if the transaction is in prepared state\&.
 197 .RE
 198 .sp
 199 If all <ref>s can be locked with matching <old\-oid>s simultaneously, all modifications are performed\&. Otherwise, no modifications are performed\&. Note that while each individual <ref> is updated or deleted atomically, a concurrent reader may still see a subset of the modifications\&.
 200 .SH "LOGGING UPDATES"
 201 .sp
 202 If config parameter "core\&.logAllRefUpdates" is true and the ref is one under "refs/heads/", "refs/remotes/", "refs/notes/", or a pseudoref like HEAD or ORIG_HEAD; or the file "$GIT_DIR/logs/<ref>" exists then \fBgit update\-ref\fR 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:
 203 .sp
 204 .if n \{\
 205 .RS 4
 206 .\}
 207 .nf
 208 oldsha1 SP newsha1 SP committer LF
 209 .fi
 210 .if n \{\
 211 .RE
 212 .\}
 213 .sp
 214 Where "oldsha1" is the 40 character hexadecimal value previously stored in <ref>, "newsha1" is the 40 character hexadecimal value of <new\-oid> and "committer" is the committer\(cqs name, email address and date in the standard Git committer ident format\&.
 215 .sp
 216 Optionally with \-m:
 217 .sp
 218 .if n \{\
 219 .RS 4
 220 .\}
 221 .nf
 222 oldsha1 SP newsha1 SP committer TAB message LF
 223 .fi
 224 .if n \{\
 225 .RE
 226 .\}
 227 .sp
 228 Where all fields are as described above and "message" is the value supplied to the \-m option\&.
 229 .sp
 230 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 available\&.
 231 .SH "GIT"
 232 .sp
 233 Part of the \fBgit\fR(1) suite