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-receive-pack.1 (11780B)


  1. '\" t
  2. .\" Title: git-receive-pack
  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\-RECEIVE\-PACK" "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-receive-pack \- Receive what is pushed into the repository
  32. .SH "SYNOPSIS"
  33. .sp
  34. .nf
  35. \fIgit receive\-pack\fR <git\-dir>
  36. .fi
  37. .SH "DESCRIPTION"
  38. .sp
  39. Invoked by \fIgit send\-pack\fR and updates the repository with the information fed from the remote end\&.
  40. .sp
  41. This command is usually not invoked directly by the end user\&. The UI for the protocol is on the \fIgit send\-pack\fR side, and the program pair is meant to be used to push updates to a remote repository\&. For pull operations, see \fBgit-fetch-pack\fR(1)\&.
  42. .sp
  43. The command allows for the creation and fast\-forwarding of sha1 refs (heads/tags) on the remote end (strictly speaking, it is the local end \fIgit\-receive\-pack\fR runs, but to the user who is sitting at the send\-pack end, it is updating the remote\&. Confused?)
  44. .sp
  45. There are other real\-world examples of using update and post\-update hooks found in the Documentation/howto directory\&.
  46. .sp
  47. \fIgit\-receive\-pack\fR honours the receive\&.denyNonFastForwards config option, which tells it if updates to a ref should be denied if they are not fast\-forwards\&.
  48. .sp
  49. A number of other receive\&.* config options are available to tweak its behavior, see \fBgit-config\fR(1)\&.
  50. .SH "OPTIONS"
  51. .PP
  52. <git\-dir>
  53. .RS 4
  54. The repository to sync into\&.
  55. .RE
  56. .PP
  57. \-\-http\-backend\-info\-refs
  58. .RS 4
  59. Used by
  60. \fBgit-http-backend\fR(1)
  61. to serve up
  62. \fB$GIT_URL/info/refs\fR?service=git\-receive\-pack requests\&. See
  63. \fB\-\-http\-backend\-info\-refs\fR
  64. in
  65. \fBgit-upload-pack\fR(1)\&.
  66. .RE
  67. .SH "PRE\-RECEIVE HOOK"
  68. .sp
  69. Before any ref is updated, if $GIT_DIR/hooks/pre\-receive file exists and is executable, it will be invoked once with no parameters\&. The standard input of the hook will be one line per ref to be updated:
  70. .sp
  71. .if n \{\
  72. .RS 4
  73. .\}
  74. .nf
  75. sha1\-old SP sha1\-new SP refname LF
  76. .fi
  77. .if n \{\
  78. .RE
  79. .\}
  80. .sp
  81. The refname value is relative to $GIT_DIR; e\&.g\&. for the master head this is "refs/heads/master"\&. The two sha1 values before each refname are the object names for the refname before and after the update\&. Refs to be created will have sha1\-old equal to 0{40}, while refs to be deleted will have sha1\-new equal to 0{40}, otherwise sha1\-old and sha1\-new should be valid objects in the repository\&.
  82. .sp
  83. When accepting a signed push (see \fBgit-push\fR(1)), the signed push certificate is stored in a blob and an environment variable \fBGIT_PUSH_CERT\fR can be consulted for its object name\&. See the description of \fBpost\-receive\fR hook for an example\&. In addition, the certificate is verified using GPG and the result is exported with the following environment variables:
  84. .PP
  85. \fBGIT_PUSH_CERT_SIGNER\fR
  86. .RS 4
  87. The name and the e\-mail address of the owner of the key that signed the push certificate\&.
  88. .RE
  89. .PP
  90. \fBGIT_PUSH_CERT_KEY\fR
  91. .RS 4
  92. The GPG key ID of the key that signed the push certificate\&.
  93. .RE
  94. .PP
  95. \fBGIT_PUSH_CERT_STATUS\fR
  96. .RS 4
  97. The status of GPG verification of the push certificate, using the same mnemonic as used in %G? format of
  98. \fBgit\fR
  99. \fBlog\fR
  100. family of commands (see
  101. \fBgit-log\fR(1))\&.
  102. .RE
  103. .PP
  104. \fBGIT_PUSH_CERT_NONCE\fR
  105. .RS 4
  106. The nonce string the process asked the signer to include in the push certificate\&. If this does not match the value recorded on the "nonce" header in the push certificate, it may indicate that the certificate is a valid one that is being replayed from a separate "git push" session\&.
  107. .RE
  108. .PP
  109. \fBGIT_PUSH_CERT_NONCE_STATUS\fR
  110. .RS 4
  111. .PP
  112. \fBUNSOLICITED\fR
  113. .RS 4
  114. "git push \-\-signed" sent a nonce when we did not ask it to send one\&.
  115. .RE
  116. .PP
  117. \fBMISSING\fR
  118. .RS 4
  119. "git push \-\-signed" did not send any nonce header\&.
  120. .RE
  121. .PP
  122. \fBBAD\fR
  123. .RS 4
  124. "git push \-\-signed" sent a bogus nonce\&.
  125. .RE
  126. .PP
  127. \fBOK\fR
  128. .RS 4
  129. "git push \-\-signed" sent the nonce we asked it to send\&.
  130. .RE
  131. .PP
  132. \fBSLOP\fR
  133. .RS 4
  134. "git push \-\-signed" sent a nonce different from what we asked it to send now, but in a previous session\&. See
  135. \fBGIT_PUSH_CERT_NONCE_SLOP\fR
  136. environment variable\&.
  137. .RE
  138. .RE
  139. .PP
  140. \fBGIT_PUSH_CERT_NONCE_SLOP\fR
  141. .RS 4
  142. "git push \-\-signed" sent a nonce different from what we asked it to send now, but in a different session whose starting time is different by this many seconds from the current session\&. Only meaningful when
  143. \fBGIT_PUSH_CERT_NONCE_STATUS\fR
  144. says
  145. \fBSLOP\fR\&. Also read about
  146. \fBreceive\&.certNonceSlop\fR
  147. variable in
  148. \fBgit-config\fR(1)\&.
  149. .RE
  150. .sp
  151. This hook is called before any refname is updated and before any fast\-forward checks are performed\&.
  152. .sp
  153. If the pre\-receive hook exits with a non\-zero exit status no updates will be performed, and the update, post\-receive and post\-update hooks will not be invoked either\&. This can be useful to quickly bail out if the update is not to be supported\&.
  154. .sp
  155. See the notes on the quarantine environment below\&.
  156. .SH "UPDATE HOOK"
  157. .sp
  158. Before each ref is updated, if $GIT_DIR/hooks/update file exists and is executable, it is invoked once per ref, with three parameters:
  159. .sp
  160. .if n \{\
  161. .RS 4
  162. .\}
  163. .nf
  164. $GIT_DIR/hooks/update refname sha1\-old sha1\-new
  165. .fi
  166. .if n \{\
  167. .RE
  168. .\}
  169. .sp
  170. The refname parameter is relative to $GIT_DIR; e\&.g\&. for the master head this is "refs/heads/master"\&. The two sha1 arguments are the object names for the refname before and after the update\&. Note that the hook is called before the refname is updated, so either sha1\-old is 0{40} (meaning there is no such ref yet), or it should match what is recorded in refname\&.
  171. .sp
  172. The hook should exit with non\-zero status if it wants to disallow updating the named ref\&. Otherwise it should exit with zero\&.
  173. .sp
  174. Successful execution (a zero exit status) of this hook does not ensure the ref will actually be updated, it is only a prerequisite\&. As such it is not a good idea to send notices (e\&.g\&. email) from this hook\&. Consider using the post\-receive hook instead\&.
  175. .SH "POST\-RECEIVE HOOK"
  176. .sp
  177. After all refs were updated (or attempted to be updated), if any ref update was successful, and if $GIT_DIR/hooks/post\-receive file exists and is executable, it will be invoked once with no parameters\&. The standard input of the hook will be one line for each successfully updated ref:
  178. .sp
  179. .if n \{\
  180. .RS 4
  181. .\}
  182. .nf
  183. sha1\-old SP sha1\-new SP refname LF
  184. .fi
  185. .if n \{\
  186. .RE
  187. .\}
  188. .sp
  189. The refname value is relative to $GIT_DIR; e\&.g\&. for the master head this is "refs/heads/master"\&. The two sha1 values before each refname are the object names for the refname before and after the update\&. Refs that were created will have sha1\-old equal to 0{40}, while refs that were deleted will have sha1\-new equal to 0{40}, otherwise sha1\-old and sha1\-new should be valid objects in the repository\&.
  190. .sp
  191. The \fBGIT_PUSH_CERT\fR* environment variables can be inspected, just as in \fBpre\-receive\fR hook, after accepting a signed push\&.
  192. .sp
  193. Using this hook, it is easy to generate mails describing the updates to the repository\&. This example script sends one mail message per ref listing the commits pushed to the repository, and logs the push certificates of signed pushes with good signatures to a logger service:
  194. .sp
  195. .if n \{\
  196. .RS 4
  197. .\}
  198. .nf
  199. #!/bin/sh
  200. # mail out commit update information\&.
  201. while read oval nval ref
  202. do
  203. if expr "$oval" : \*(Aq0*$\*(Aq >/dev/null
  204. then
  205. echo "Created a new ref, with the following commits:"
  206. git rev\-list \-\-pretty "$nval"
  207. else
  208. echo "New commits:"
  209. git rev\-list \-\-pretty "$nval" "^$oval"
  210. fi |
  211. mail \-s "Changes to ref $ref" commit\-list@mydomain
  212. done
  213. # log signed push certificate, if any
  214. if test \-n "${GIT_PUSH_CERT\-}" && test ${GIT_PUSH_CERT_STATUS} = G
  215. then
  216. (
  217. echo expected nonce is ${GIT_PUSH_NONCE}
  218. git cat\-file blob ${GIT_PUSH_CERT}
  219. ) | mail \-s "push certificate from $GIT_PUSH_CERT_SIGNER" push\-log@mydomain
  220. fi
  221. exit 0
  222. .fi
  223. .if n \{\
  224. .RE
  225. .\}
  226. .sp
  227. The exit code from this hook invocation is ignored, however a non\-zero exit code will generate an error message\&.
  228. .sp
  229. Note that it is possible for refname to not have sha1\-new when this hook runs\&. This can easily occur if another user modifies the ref after it was updated by \fIgit\-receive\-pack\fR, but before the hook was able to evaluate it\&. It is recommended that hooks rely on sha1\-new rather than the current value of refname\&.
  230. .SH "POST\-UPDATE HOOK"
  231. .sp
  232. After all other processing, if at least one ref was updated, and if $GIT_DIR/hooks/post\-update file exists and is executable, then post\-update will be called with the list of refs that have been updated\&. This can be used to implement any repository wide cleanup tasks\&.
  233. .sp
  234. The exit code from this hook invocation is ignored; the only thing left for \fIgit\-receive\-pack\fR to do at that point is to exit itself anyway\&.
  235. .sp
  236. This hook can be used, for example, to run \fBgit\fR \fBupdate\-server\-info\fR if the repository is packed and is served via a dumb transport\&.
  237. .sp
  238. .if n \{\
  239. .RS 4
  240. .\}
  241. .nf
  242. #!/bin/sh
  243. exec git update\-server\-info
  244. .fi
  245. .if n \{\
  246. .RE
  247. .\}
  248. .SH "QUARANTINE ENVIRONMENT"
  249. .sp
  250. When \fBreceive\-pack\fR takes in objects, they are placed into a temporary "quarantine" directory within the \fB$GIT_DIR/objects\fR directory and migrated into the main object store only after the \fBpre\-receive\fR hook has completed\&. If the push fails before then, the temporary directory is removed entirely\&.
  251. .sp
  252. This has a few user\-visible effects and caveats:
  253. .sp
  254. .RS 4
  255. .ie n \{\
  256. \h'-04' 1.\h'+01'\c
  257. .\}
  258. .el \{\
  259. .sp -1
  260. .IP " 1." 4.2
  261. .\}
  262. Pushes which fail due to problems with the incoming pack, missing objects, or due to the
  263. \fBpre\-receive\fR
  264. hook will not leave any on\-disk data\&. This is usually helpful to prevent repeated failed pushes from filling up your disk, but can make debugging more challenging\&.
  265. .RE
  266. .sp
  267. .RS 4
  268. .ie n \{\
  269. \h'-04' 2.\h'+01'\c
  270. .\}
  271. .el \{\
  272. .sp -1
  273. .IP " 2." 4.2
  274. .\}
  275. Any objects created by the
  276. \fBpre\-receive\fR
  277. hook will be created in the quarantine directory (and migrated only if it succeeds)\&.
  278. .RE
  279. .sp
  280. .RS 4
  281. .ie n \{\
  282. \h'-04' 3.\h'+01'\c
  283. .\}
  284. .el \{\
  285. .sp -1
  286. .IP " 3." 4.2
  287. .\}
  288. The
  289. \fBpre\-receive\fR
  290. hook MUST NOT update any refs to point to quarantined objects\&. Other programs accessing the repository will not be able to see the objects (and if the pre\-receive hook fails, those refs would become corrupted)\&. For safety, any ref updates from within
  291. \fBpre\-receive\fR
  292. are automatically rejected\&.
  293. .RE
  294. .SH "SEE ALSO"
  295. .sp
  296. \fBgit-send-pack\fR(1), \fBgitnamespaces\fR(7)
  297. .SH "GIT"
  298. .sp
  299. Part of the \fBgit\fR(1) suite