logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

git-update-ref.1 (8897B)


  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: 2025-03-14
  6. .\" Manual: Git Manual
  7. .\" Source: Git 2.49.0
  8. .\" Language: English
  9. .\"
  10. .TH "GIT\-UPDATE\-REF" "1" "2025-03-14" "Git 2\&.49\&.0" "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\fR \fBupdate\-ref\fR \fBHEAD\fR \fI<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\fR \fBupdate\-ref\fR \fBrefs/heads/master\fR \fI<new\-oid>\fR \fI<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. The final arguments are object names; this command without any options does not support updating a symbolic ref to point to another ref (see \fBgit-symbolic-ref\fR(1))\&. But \fBgit\fR \fBupdate\-ref\fR \fB\-\-stdin\fR does have the \fBsymref\-\fR* commands so that regular refs and symbolic refs can be committed in the same transaction\&.
  44. .sp
  45. If \-\-no\-deref is given, <ref> itself is overwritten, rather than the result of following the symbolic pointers\&.
  46. .sp
  47. With \fB\-d\fR, it deletes the named <ref> after verifying that it still contains <old\-oid>\&.
  48. .sp
  49. With \fB\-\-stdin\fR, update\-ref reads instructions from standard input and performs all modifications together\&. Specify commands of the form:
  50. .sp
  51. .if n \{\
  52. .RS 4
  53. .\}
  54. .nf
  55. update SP <ref> SP <new\-oid> [SP <old\-oid>] LF
  56. create SP <ref> SP <new\-oid> LF
  57. delete SP <ref> [SP <old\-oid>] LF
  58. verify SP <ref> [SP <old\-oid>] LF
  59. symref\-update SP <ref> SP <new\-target> [SP (ref SP <old\-target> | oid SP <old\-oid>)] LF
  60. symref\-create SP <ref> SP <new\-target> LF
  61. symref\-delete SP <ref> [SP <old\-target>] LF
  62. symref\-verify SP <ref> [SP <old\-target>] LF
  63. option SP <opt> LF
  64. start LF
  65. prepare LF
  66. commit LF
  67. abort LF
  68. .fi
  69. .if n \{\
  70. .RE
  71. .\}
  72. .sp
  73. With \fB\-\-create\-reflog\fR, update\-ref will create a reflog for each ref even if one would not ordinarily be created\&.
  74. .sp
  75. 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\&.
  76. .sp
  77. Alternatively, use \fB\-z\fR to specify in NUL\-terminated format, without quoting:
  78. .sp
  79. .if n \{\
  80. .RS 4
  81. .\}
  82. .nf
  83. update SP <ref> NUL <new\-oid> NUL [<old\-oid>] NUL
  84. create SP <ref> NUL <new\-oid> NUL
  85. delete SP <ref> NUL [<old\-oid>] NUL
  86. verify SP <ref> NUL [<old\-oid>] NUL
  87. symref\-update SP <ref> NUL <new\-target> [NUL (ref NUL <old\-target> | oid NUL <old\-oid>)] NUL
  88. symref\-create SP <ref> NUL <new\-target> NUL
  89. symref\-delete SP <ref> [NUL <old\-target>] NUL
  90. symref\-verify SP <ref> [NUL <old\-target>] NUL
  91. option SP <opt> NUL
  92. start NUL
  93. prepare NUL
  94. commit NUL
  95. abort NUL
  96. .fi
  97. .if n \{\
  98. .RE
  99. .\}
  100. .sp
  101. In this format, use 40 "0" to specify a zero value, and use the empty string to specify a missing value\&.
  102. .sp
  103. 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:
  104. .PP
  105. update
  106. .RS 4
  107. 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\&.
  108. .RE
  109. .PP
  110. create
  111. .RS 4
  112. Create <ref> with <new\-oid> after verifying that it does not exist\&. The given <new\-oid> may not be zero\&.
  113. .RE
  114. .PP
  115. delete
  116. .RS 4
  117. Delete <ref> after verifying that it exists with <old\-oid>, if given\&. If given, <old\-oid> may not be zero\&.
  118. .RE
  119. .PP
  120. symref\-update
  121. .RS 4
  122. 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\&.
  123. .RE
  124. .PP
  125. verify
  126. .RS 4
  127. Verify <ref> against <old\-oid> but do not change it\&. If <old\-oid> is zero or missing, the ref must not exist\&.
  128. .RE
  129. .sp
  130. symref\-create: Create symbolic ref <ref> with <new\-target> after verifying that it does not exist\&.
  131. .PP
  132. symref\-delete
  133. .RS 4
  134. Delete <ref> after verifying that it exists with <old\-target>, if given\&.
  135. .RE
  136. .PP
  137. symref\-verify
  138. .RS 4
  139. 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
  140. \fBno\-deref\fR
  141. mode\&.
  142. .RE
  143. .PP
  144. option
  145. .RS 4
  146. Modify the behavior of the next command naming a <ref>\&. The only valid option is
  147. \fBno\-deref\fR
  148. to avoid dereferencing a symbolic ref\&.
  149. .RE
  150. .PP
  151. start
  152. .RS 4
  153. 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\&.
  154. .RE
  155. .PP
  156. prepare
  157. .RS 4
  158. 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\&.
  159. .RE
  160. .PP
  161. commit
  162. .RS 4
  163. Commit all reference updates queued for the transaction, ending the transaction\&.
  164. .RE
  165. .PP
  166. abort
  167. .RS 4
  168. Abort the transaction, releasing all locks if the transaction is in prepared state\&.
  169. .RE
  170. .sp
  171. 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\&.
  172. .SH "LOGGING UPDATES"
  173. .sp
  174. 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\fR \fBupdate\-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:
  175. .sp
  176. .if n \{\
  177. .RS 4
  178. .\}
  179. .nf
  180. oldsha1 SP newsha1 SP committer LF
  181. .fi
  182. .if n \{\
  183. .RE
  184. .\}
  185. .sp
  186. 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\&.
  187. .sp
  188. Optionally with \-m:
  189. .sp
  190. .if n \{\
  191. .RS 4
  192. .\}
  193. .nf
  194. oldsha1 SP newsha1 SP committer TAB message LF
  195. .fi
  196. .if n \{\
  197. .RE
  198. .\}
  199. .sp
  200. Where all fields are as described above and "message" is the value supplied to the \-m option\&.
  201. .sp
  202. 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\&.
  203. .SH "NOTES"
  204. .sp
  205. Symbolic refs were initially implemented using symbolic links\&. This is now deprecated since not all filesystems support symbolic links\&.
  206. .sp
  207. This command 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)\&.
  208. .SH "SEE ALSO"
  209. .sp
  210. \fBgit-symbolic-ref\fR(1)
  211. .SH "GIT"
  212. .sp
  213. Part of the \fBgit\fR(1) suite