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 vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2023-08-04
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.42.0.rc0
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-UPDATE\-REF" "1" "2023\-08\-04" "Git 2\&.42\&.0\&.rc0" "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> [<oldvalue>] | [\-\-create\-reflog] <ref> <newvalue> [<oldvalue>] | \-\-stdin [\-z])
  36 .fi
  37 .sp
  38 .SH "DESCRIPTION"
  39 .sp
  40 Given two arguments, stores the <newvalue> in the <ref>, possibly dereferencing the symbolic refs\&. E\&.g\&. \fBgit update\-ref HEAD <newvalue>\fR updates the current branch head to the new object\&.
  41 .sp
  42 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\&. \fBgit update\-ref refs/heads/master <newvalue> <oldvalue>\fR 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\&.
  43 .sp
  44 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:"\&.
  45 .sp
  46 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)\&.
  47 .sp
  48 If \-\-no\-deref is given, <ref> itself is overwritten, rather than the result of following the symbolic pointers\&.
  49 .sp
  50 In general, using
  51 .sp
  52 .if n \{\
  53 .RS 4
  54 .\}
  55 .nf
  56 git update\-ref HEAD "$head"
  57 .fi
  58 .if n \{\
  59 .RE
  60 .\}
  61 .sp
  62 should be a \fIlot\fR safer than doing
  63 .sp
  64 .if n \{\
  65 .RS 4
  66 .\}
  67 .nf
  68 echo "$head" > "$GIT_DIR/HEAD"
  69 .fi
  70 .if n \{\
  71 .RE
  72 .\}
  73 .sp
  74 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)\&.
  75 .sp
  76 With \fB\-d\fR flag, it deletes the named <ref> after verifying it still contains <oldvalue>\&.
  77 .sp
  78 With \fB\-\-stdin\fR, update\-ref reads instructions from standard input and performs all modifications together\&. Specify commands of the form:
  79 .sp
  80 .if n \{\
  81 .RS 4
  82 .\}
  83 .nf
  84 update SP <ref> SP <newvalue> [SP <oldvalue>] LF
  85 create SP <ref> SP <newvalue> LF
  86 delete SP <ref> [SP <oldvalue>] LF
  87 verify SP <ref> [SP <oldvalue>] LF
  88 option SP <opt> LF
  89 start LF
  90 prepare LF
  91 commit LF
  92 abort LF
  93 .fi
  94 .if n \{\
  95 .RE
  96 .\}
  97 .sp
  98 With \fB\-\-create\-reflog\fR, update\-ref will create a reflog for each ref even if one would not ordinarily be created\&.
  99 .sp
 100 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\&.
 101 .sp
 102 Alternatively, use \fB\-z\fR to specify in NUL\-terminated format, without quoting:
 103 .sp
 104 .if n \{\
 105 .RS 4
 106 .\}
 107 .nf
 108 update SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL
 109 create SP <ref> NUL <newvalue> NUL
 110 delete SP <ref> NUL [<oldvalue>] NUL
 111 verify SP <ref> NUL [<oldvalue>] NUL
 112 option SP <opt> NUL
 113 start NUL
 114 prepare NUL
 115 commit NUL
 116 abort NUL
 117 .fi
 118 .if n \{\
 119 .RE
 120 .\}
 121 .sp
 122 In this format, use 40 "0" to specify a zero value, and use the empty string to specify a missing value\&.
 123 .sp
 124 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:
 125 .PP
 126 update
 127 .RS 4
 128 Set <ref> to <newvalue> after verifying <oldvalue>, if given\&. Specify a zero <newvalue> to ensure the ref does not exist after the update and/or a zero <oldvalue> to make sure the ref does not exist before the update\&.
 129 .RE
 130 .PP
 131 create
 132 .RS 4
 133 Create <ref> with <newvalue> after verifying it does not exist\&. The given <newvalue> may not be zero\&.
 134 .RE
 135 .PP
 136 delete
 137 .RS 4
 138 Delete <ref> after verifying it exists with <oldvalue>, if given\&. If given, <oldvalue> may not be zero\&.
 139 .RE
 140 .PP
 141 verify
 142 .RS 4
 143 Verify <ref> against <oldvalue> but do not change it\&. If <oldvalue> is zero or missing, the ref must not exist\&.
 144 .RE
 145 .PP
 146 option
 147 .RS 4
 148 Modify behavior of the next command naming a <ref>\&. The only valid option is
 149 \fBno\-deref\fR
 150 to avoid dereferencing a symbolic ref\&.
 151 .RE
 152 .PP
 153 start
 154 .RS 4
 155 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\&.
 156 .RE
 157 .PP
 158 prepare
 159 .RS 4
 160 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\&.
 161 .RE
 162 .PP
 163 commit
 164 .RS 4
 165 Commit all reference updates queued for the transaction, ending the transaction\&.
 166 .RE
 167 .PP
 168 abort
 169 .RS 4
 170 Abort the transaction, releasing all locks if the transaction is in prepared state\&.
 171 .RE
 172 .sp
 173 If all <ref>s can be locked with matching <oldvalue>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\&.
 174 .SH "LOGGING UPDATES"
 175 .sp
 176 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:
 177 .sp
 178 .if n \{\
 179 .RS 4
 180 .\}
 181 .nf
 182 oldsha1 SP newsha1 SP committer LF
 183 .fi
 184 .if n \{\
 185 .RE
 186 .\}
 187 .sp
 188 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\(cqs name, email address and date in the standard Git committer ident format\&.
 189 .sp
 190 Optionally with \-m:
 191 .sp
 192 .if n \{\
 193 .RS 4
 194 .\}
 195 .nf
 196 oldsha1 SP newsha1 SP committer TAB message LF
 197 .fi
 198 .if n \{\
 199 .RE
 200 .\}
 201 .sp
 202 Where all fields are as described above and "message" is the value supplied to the \-m option\&.
 203 .sp
 204 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\&.
 205 .SH "GIT"
 206 .sp
 207 Part of the \fBgit\fR(1) suite