Debian Codegraph @

upstream/fedora-44/man1/perlgit.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLGIT 1"
61 .TH PERLGIT 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perlgit \- Detailed information about git and the Perl repository
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 This document provides details on using git to develop Perl. If you are
71 just interested in working on a quick patch, see perlhack first.
72 This document is intended for people who are regular contributors to
73 Perl, including those with write access to the git repository.
74 .SH "CLONING THE REPOSITORY"
75 .IX Header "CLONING THE REPOSITORY"
76 All of Perl\*(Aqs source code is kept centrally in a Git repository at
77 \&\fIgithub.com\fR.
78 .PP
79 You can make a read\-only clone of the repository by running:
80 .PP
81 .Vb 1
82 \& % git clone [email protected]:Perl/perl5.git perl
83 .Ve
84 .PP
85 If you cannot use that for firewall reasons, you can also clone via http:
86 .PP
87 .Vb 1
88 \& % git clone https://github.com/Perl/perl5.git perl
89 .Ve
90 .SH "WORKING WITH THE REPOSITORY"
91 .IX Header "WORKING WITH THE REPOSITORY"
92 Once you have changed into the repository directory, you can inspect
93 it. After a clone the repository will contain a single local branch,
94 which will be the current branch as well, as indicated by the asterisk.
95 .PP
96 .Vb 2
97 \& % git branch
98 \& * blead
99 .Ve
100 .PP
101 Using the \-a switch to \f(CW\*(C`branch\*(C'\fR will also show the remote tracking
102 branches in the repository:
103 .PP
104 .Vb 5
105 \& % git branch \-a
106 \& * blead
107 \& origin/HEAD
108 \& origin/blead
109 \& ...
110 .Ve
111 .PP
112 The branches that begin with "origin" correspond to the "git remote"
113 that you cloned from (which is named "origin"). Each branch on the
114 remote will be exactly tracked by these branches. You should NEVER do
115 work on these remote tracking branches. You only ever do work in a
116 local branch. Local branches can be configured to automerge (on pull)
117 from a designated remote tracking branch. This is the case with the
118 default branch \f(CW\*(C`blead\*(C'\fR which will be configured to merge from the
119 remote tracking branch \f(CW\*(C`origin/blead\*(C'\fR.
120 .PP
121 You can see recent commits:
122 .PP
123 .Vb 1
124 \& % git log
125 .Ve
126 .PP
127 And pull new changes from the repository, and update your local
128 repository (must be clean first)
129 .PP
130 .Vb 1
131 \& % git pull
132 .Ve
133 .PP
134 Assuming we are on the branch \f(CW\*(C`blead\*(C'\fR immediately after a pull, this
135 command would be more or less equivalent to:
136 .PP
137 .Vb 2
138 \& % git fetch
139 \& % git merge origin/blead
140 .Ve
141 .PP
142 In fact if you want to update your local repository without touching
143 your working directory you do:
144 .PP
145 .Vb 1
146 \& % git fetch
147 .Ve
148 .PP
149 And if you want to update your remote\-tracking branches for all defined
150 remotes simultaneously you can do
151 .PP
152 .Vb 1
153 \& % git remote update
154 .Ve
155 .PP
156 Neither of these last two commands will update your working directory,
157 however both will update the remote\-tracking branches in your
158 repository.
159 .PP
160 To make a local branch of a remote branch:
161 .PP
162 .Vb 1
163 \& % git checkout \-b maint\-5.10 origin/maint\-5.10
164 .Ve
165 .PP
166 To switch back to blead:
167 .PP
168 .Vb 1
169 \& % git checkout blead
170 .Ve
171 .SS "Finding out your status"
172 .IX Subsection "Finding out your status"
173 The most common git command you will use will probably be
174 .PP
175 .Vb 1
176 \& % git status
177 .Ve
178 .PP
179 This command will produce as output a description of the current state
180 of the repository, including modified files and unignored untracked
181 files, and in addition it will show things like what files have been
182 staged for the next commit, and usually some useful information about
183 how to change things. For instance the following:
184 .PP
185 .Vb 3
186 \& % git status
187 \& On branch blead
188 \& Your branch is ahead of \*(Aqorigin/blead\*(Aq by 1 commit.
189 \&
190 \& Changes to be committed:
191 \& (use "git reset HEAD <file>..." to unstage)
192 \&
193 \& modified: pod/perlgit.pod
194 \&
195 \& Changes not staged for commit:
196 \& (use "git add <file>..." to update what will be committed)
197 \& (use "git checkout \-\- <file>..." to discard changes in working
198 \& directory)
199 \&
200 \& modified: pod/perlgit.pod
201 \&
202 \& Untracked files:
203 \& (use "git add <file>..." to include in what will be committed)
204 \&
205 \& deliberate.untracked
206 .Ve
207 .PP
208 This shows that there were changes to this document staged for commit,
209 and that there were further changes in the working directory not yet
210 staged. It also shows that there was an untracked file in the working
211 directory, and as you can see shows how to change all of this. It also
212 shows that there is one commit on the working branch \f(CW\*(C`blead\*(C'\fR which has
213 not been pushed to the \f(CW\*(C`origin\*(C'\fR remote yet. \fBNOTE\fR: This output
214 is also what you see as a template if you do not provide a message to
215 \&\f(CW\*(C`git commit\*(C'\fR.
216 .SS "Patch workflow"
217 .IX Subsection "Patch workflow"
218 First, please read perlhack for details on hacking the Perl core.
219 That document covers many details on how to create a good patch.
220 .PP
221 If you already have a Perl repository, you should ensure that you\*(Aqre on
222 the \fIblead\fR branch, and your repository is up to date:
223 .PP
224 .Vb 2
225 \& % git checkout blead
226 \& % git pull
227 .Ve
228 .PP
229 It\*(Aqs preferable to patch against the latest blead version, since this
230 is where new development occurs for all changes other than critical bug
231 fixes. Critical bug fix patches should be made against the relevant
232 maint branches, or should be submitted with a note indicating all the
233 branches where the fix should be applied.
234 .PP
235 Now that we have everything up to date, we need to create a temporary
236 new branch for these changes and switch into it:
237 .PP
238 .Vb 1
239 \& % git checkout \-b orange
240 .Ve
241 .PP
242 which is the short form of
243 .PP
244 .Vb 2
245 \& % git branch orange
246 \& % git checkout orange
247 .Ve
248 .PP
249 Creating a topic branch makes it easier for the maintainers to rebase
250 or merge back into the master blead for a more linear history. If you
251 don\*(Aqt work on a topic branch the maintainer has to manually cherry pick
252 your changes onto blead before they can be applied.
253 .PP
254 That\*(Aqll get you scolded on perl5\-porters, so don\*(Aqt do that. Be Awesome.
255 .PP
256 Then make your changes. For example, if Leon Brocard changes his name
257 to Orange Brocard, we should change his name in the AUTHORS file:
258 .PP
259 .Vb 1
260 \& % perl \-pi \-e \*(Aqs{Leon Brocard}{Orange Brocard}\*(Aq AUTHORS
261 .Ve
262 .PP
263 You can see what files are changed:
264 .PP
265 .Vb 4
266 \& % git status
267 \& On branch orange
268 \& Changes to be committed:
269 \& (use "git reset HEAD <file>..." to unstage)
270 \&
271 \& modified: AUTHORS
272 .Ve
273 .PP
274 And you can see the changes:
275 .PP
276 .Vb 10
277 \& % git diff
278 \& diff \-\-git a/AUTHORS b/AUTHORS
279 \& index 293dd70..722c93e 100644
280 \& \-\-\- a/AUTHORS
281 \& +++ b/AUTHORS
282 \& @@ \-541,7 +541,7 @@ Lars Hecking <[email protected]>
283 \& Laszlo Molnar <[email protected]>
284 \& Leif Huhn <[email protected]>
285 \& Len Johnson <[email protected]>
286 \& \-Leon Brocard <[email protected]>
287 \& +Orange Brocard <[email protected]>
288 \& Les Peters <[email protected]>
289 \& Lesley Binks <[email protected]>
290 \& Lincoln D. Stein <[email protected]>
291 .Ve
292 .PP
293 Now commit your change locally:
294 .PP
295 .Vb 3
296 \& % git commit \-a \-m \*(AqRename Leon Brocard to Orange Brocard\*(Aq
297 \& Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
298 \& 1 files changed, 1 insertions(+), 1 deletions(\-)
299 .Ve
300 .PP
301 The \f(CW\*(C`\-a\*(C'\fR option is used to include all files that git tracks that you
302 have changed. If at this time, you only want to commit some of the
303 files you have worked on, you can omit the \f(CW\*(C`\-a\*(C'\fR and use the command
304 \&\f(CW\*(C`git\ add\ \fR\f(CIFILE\ ...\fR\f(CW\*(C'\fR before doing the commit. \f(CW\*(C`git\ add\ \-\-interactive\*(C'\fR allows you to even just commit portions of files
305 instead of all the changes in them.
306 .PP
307 The \f(CW\*(C`\-m\*(C'\fR option is used to specify the commit message. If you omit it,
308 git will open a text editor for you to compose the message
309 interactively. This is useful when the changes are more complex than
310 the sample given here, and, depending on the editor, to know that the
311 first line of the commit message doesn\*(Aqt exceed the 50 character legal
312 maximum. See "Commit message" in perlhack for more information about what
313 makes a good commit message.
314 .PP
315 Once you\*(Aqve finished writing your commit message and exited your
316 editor, git will write your change to disk and tell you something like
317 this:
318 .PP
319 .Vb 2
320 \& Created commit daf8e63: explain git status and stuff about remotes
321 \& 1 files changed, 83 insertions(+), 3 deletions(\-)
322 .Ve
323 .PP
324 If you re\-run \f(CW\*(C`git status\*(C'\fR, you should see something like this:
325 .PP
326 .Vb 4
327 \& % git status
328 \& On branch orange
329 \& Untracked files:
330 \& (use "git add <file>..." to include in what will be committed)
331 \&
332 \& deliberate.untracked
333 \&
334 \& nothing added to commit but untracked files present (use "git add" to
335 \& track)
336 .Ve
337 .PP
338 When in doubt, before you do anything else, check your status and read
339 it carefully, many questions are answered directly by the git status
340 output.
341 .PP
342 You can examine your last commit with:
343 .PP
344 .Vb 1
345 \& % git show HEAD
346 .Ve
347 .PP
348 and if you are not happy with either the description or the patch
349 itself you can fix it up by editing the files once more and then issue:
350 .PP
351 .Vb 1
352 \& % git commit \-a \-\-amend
353 .Ve
354 .PP
355 Now, create a fork on GitHub to push your branch to, and add it as a
356 remote if you haven\*(Aqt already, as described in the GitHub documentation
357 at <https://help.github.com/en/articles/working\-with\-forks>:
358 .PP
359 .Vb 1
360 \& % git remote add fork [email protected]:MyUser/perl5.git
361 .Ve
362 .PP
363 And push the branch to your fork:
364 .PP
365 .Vb 1
366 \& % git push \-u fork orange
367 .Ve
368 .PP
369 You should now submit a Pull Request (PR) on GitHub from the new branch
370 to blead. For more information, see the GitHub documentation at
371 <https://help.github.com/en/articles/creating\-a\-pull\-request\-from\-a\-fork>.
372 .PP
373 You can also send patch files to
374 perl5\[email protected] <mailto:[email protected]> directly if the
375 patch is not ready to be applied, but intended for discussion.
376 .PP
377 To create a patch file for all your local changes:
378 .PP
379 .Vb 2
380 \& % git format\-patch \-M blead..
381 \& 0001\-Rename\-Leon\-Brocard\-to\-Orange\-Brocard.patch
382 .Ve
383 .PP
384 Or for a lot of changes, e.g. from a topic branch:
385 .PP
386 .Vb 1
387 \& % git format\-patch \-\-stdout \-M blead.. > topic\-branch\-changes.patch
388 .Ve
389 .PP
390 If you want to delete your temporary branch, you may do so with:
391 .PP
392 .Vb 6
393 \& % git checkout blead
394 \& % git branch \-d orange
395 \& error: The branch \*(Aqorange\*(Aq is not an ancestor of your current HEAD.
396 \& If you are sure you want to delete it, run \*(Aqgit branch \-D orange\*(Aq.
397 \& % git branch \-D orange
398 \& Deleted branch orange.
399 .Ve
400 .SS "A note on derived files"
401 .IX Subsection "A note on derived files"
402 Be aware that many files in the distribution are derivative\-\-avoid
403 patching them, because git won\*(Aqt see the changes to them, and the build
404 process will overwrite them. Patch the originals instead. Most
405 utilities (like perldoc) are in this category, i.e. patch
406 \&\fIutils/perldoc.PL\fR rather than \fIutils/perldoc\fR. Similarly, don\*(Aqt
407 create patches for files under \fR\f(CI$src_root\fR\fI/ext\fR from their copies found
408 in \fI\fR\f(CI$install_root\fR\fI/lib\fR. If you are unsure about the proper location of
409 a file that may have gotten copied while building the source
410 distribution, consult the \fIMANIFEST\fR.
411 .SS "Cleaning a working directory"
412 .IX Subsection "Cleaning a working directory"
413 The command \f(CW\*(C`git clean\*(C'\fR can with varying arguments be used as a
414 replacement for \f(CW\*(C`make clean\*(C'\fR.
415 .PP
416 To reset your working directory to a pristine condition you can do:
417 .PP
418 .Vb 1
419 \& % git clean \-dxf
420 .Ve
421 .PP
422 However, be aware this will delete ALL untracked content. You can use
423 .PP
424 .Vb 1
425 \& % git clean \-Xf
426 .Ve
427 .PP
428 to remove all ignored untracked files, such as build and test
429 byproduct, but leave any manually created files alone.
430 .PP
431 If you only want to cancel some uncommitted edits, you can use \f(CW\*(C`git
432 checkout\*(C'\fR and give it a list of files to be reverted, or \f(CW\*(C`git checkout
433 \&\-f\*(C'\fR to revert them all.
434 .PP
435 If you want to cancel one or several commits, you can use \f(CW\*(C`git reset\*(C'\fR.
436 .SS Bisecting
437 .IX Subsection "Bisecting"
438 \&\f(CW\*(C`git\*(C'\fR provides a built\-in way to determine which commit should be blamed
439 for introducing a given bug. \f(CW\*(C`git bisect\*(C'\fR performs a binary search of
440 history to locate the first failing commit. It is fast, powerful and
441 flexible, but requires some setup and to automate the process an auxiliary
442 shell script is needed.
443 .PP
444 The core provides a wrapper program, \fIPorting/bisect.pl\fR, which attempts to
445 simplify as much as possible, making bisecting as simple as running a Perl
446 one\-liner. For example, if you want to know when this became an error:
447 .PP
448 .Vb 1
449 \& perl \-e \*(Aqmy $x := 2\*(Aq
450 .Ve
451 .PP
452 you simply run this:
453 .PP
454 .Vb 1
455 \& .../Porting/bisect.pl \-e \*(Aqmy $x := 2;\*(Aq
456 .Ve
457 .PP
458 Using \fIPorting/bisect.pl\fR, with one command (and no other files) it\*(Aqs easy to
459 find out
460 .IP \(bu 4
461 Which commit caused this example code to break?
462 .IP \(bu 4
463 Which commit caused this example code to start working?
464 .IP \(bu 4
465 Which commit added the first file to match this regex?
466 .IP \(bu 4
467 Which commit removed the last file to match this regex?
468 .PP
469 usually without needing to know which versions of perl to use as start and
470 end revisions, as \fIPorting/bisect.pl\fR automatically searches to find the
471 earliest stable version for which the test case passes. Run
472 \&\f(CW\*(C`Porting/bisect.pl \-\-help\*(C'\fR for the full documentation, including how to
473 set the \f(CW\*(C`Configure\*(C'\fR and build time options.
474 .PP
475 If you require more flexibility than \fIPorting/bisect.pl\fR has to offer, you\*(Aqll
476 need to run \f(CW\*(C`git bisect\*(C'\fR yourself. It\*(Aqs most useful to use \f(CW\*(C`git bisect run\*(C'\fR
477 to automate the building and testing of perl revisions. For this you\*(Aqll need
478 a shell script for \f(CW\*(C`git\*(C'\fR to call to test a particular revision. An example
479 script is \fIPorting/bisect\-example.sh\fR, which you should copy \fBoutside\fR of
480 the repository, as the bisect process will reset the state to a clean checkout
481 as it runs. The instructions below assume that you copied it as \fI~/run\fR and
482 then edited it as appropriate.
483 .PP
484 You first enter in bisect mode with:
485 .PP
486 .Vb 1
487 \& % git bisect start
488 .Ve
489 .PP
490 For example, if the bug is present on \f(CW\*(C`HEAD\*(C'\fR but wasn\*(Aqt in 5.10.0,
491 \&\f(CW\*(C`git\*(C'\fR will learn about this when you enter:
492 .PP
493 .Vb 3
494 \& % git bisect bad
495 \& % git bisect good perl\-5.10.0
496 \& Bisecting: 853 revisions left to test after this
497 .Ve
498 .PP
499 This results in checking out the median commit between \f(CW\*(C`HEAD\*(C'\fR and
500 \&\f(CW\*(C`perl\-5.10.0\*(C'\fR. You can then run the bisecting process with:
501 .PP
502 .Vb 1
503 \& % git bisect run ~/run
504 .Ve
505 .PP
506 When the first bad commit is isolated, \f(CW\*(C`git bisect\*(C'\fR will tell you so:
507 .PP
508 .Vb 4
509 \& ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
510 \& commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
511 \& Author: Dave Mitchell <[email protected]>
512 \& Date: Sat Feb 9 14:56:23 2008 +0000
513 \&
514 \& [perl #49472] Attributes + Unknown Error
515 \& ...
516 \&
517 \& bisect run success
518 .Ve
519 .PP
520 You can peek into the bisecting process with \f(CW\*(C`git bisect log\*(C'\fR and
521 \&\f(CW\*(C`git bisect visualize\*(C'\fR. \f(CW\*(C`git bisect reset\*(C'\fR will get you out of bisect
522 mode.
523 .PP
524 Please note that the first \f(CW\*(C`good\*(C'\fR state must be an ancestor of the
525 first \f(CW\*(C`bad\*(C'\fR state. If you want to search for the commit that \fIsolved\fR
526 some bug, you have to negate your test case (i.e. exit with \f(CW1\fR if OK
527 and \f(CW0\fR if not) and still mark the lower bound as \f(CW\*(C`good\*(C'\fR and the
528 upper as \f(CW\*(C`bad\*(C'\fR. The "first bad commit" has then to be understood as
529 the "first commit where the bug is solved".
530 .PP
531 \&\f(CW\*(C`git help bisect\*(C'\fR has much more information on how you can tweak your
532 binary searches.
533 .PP
534 Following bisection you may wish to configure, build and test perl at
535 commits identified by the bisection process. Sometimes, particularly
536 with older perls, \f(CW\*(C`make\*(C'\fR may fail during this process. In this case
537 you may be able to patch the source code at the older commit point. To
538 do so, please follow the suggestions provided in
539 "Building perl at older commits" in perlhack.
540 .SS "Topic branches and rewriting history"
541 .IX Subsection "Topic branches and rewriting history"
542 Individual committers should create topic branches under
543 \&\fByourname\fR/\fBsome_descriptive_name\fR:
544 .PP
545 .Vb 4
546 \& % branch="$yourname/$some_descriptive_name"
547 \& % git checkout \-b $branch
548 \& ... do local edits, commits etc ...
549 \& % git push origin \-u $branch
550 .Ve
551 .PP
552 Should you be stuck with an ancient version of git (prior to 1.7), then
553 \&\f(CW\*(C`git push\*(C'\fR will not have the \f(CW\*(C`\-u\*(C'\fR switch, and you have to replace the
554 last step with the following sequence:
555 .PP
556 .Vb 3
557 \& % git push origin $branch:refs/heads/$branch
558 \& % git config branch.$branch.remote origin
559 \& % git config branch.$branch.merge refs/heads/$branch
560 .Ve
561 .PP
562 If you want to make changes to someone else\*(Aqs topic branch, you should
563 check with its creator before making any change to it.
564 .PP
565 You
566 might sometimes find that the original author has edited the branch\*(Aqs
567 history. There are lots of good reasons for this. Sometimes, an author
568 might simply be rebasing the branch onto a newer source point.
569 Sometimes, an author might have found an error in an early commit which
570 they wanted to fix before merging the branch to blead.
571 .PP
572 Currently the master repository is configured to forbid
573 non\-fast\-forward merges. This means that the branches within can not be
574 rebased and pushed as a single step.
575 .PP
576 The only way you will ever be allowed to rebase or modify the history
577 of a pushed branch is to delete it and push it as a new branch under
578 the same name. Please think carefully about doing this. It may be
579 better to sequentially rename your branches so that it is easier for
580 others working with you to cherry\-pick their local changes onto the new
581 version. (XXX: needs explanation).
582 .PP
583 If you want to rebase a personal topic branch, you will have to delete
584 your existing topic branch and push as a new version of it. You can do
585 this via the following formula (see the explanation about \f(CW\*(C`refspec\*(C'\fR\*(Aqs
586 in the git push documentation for details) after you have rebased your
587 branch:
588 .PP
589 .Vb 4
590 \& # first rebase
591 \& % git checkout $user/$topic
592 \& % git fetch
593 \& % git rebase origin/blead
594 \&
595 \& # then "delete\-and\-push"
596 \& % git push origin :$user/$topic
597 \& % git push origin $user/$topic
598 .Ve
599 .PP
600 \&\fBNOTE:\fR it is forbidden at the repository level to delete any of the
601 "primary" branches. That is any branch matching
602 \&\f(CW\*(C`m!^(blead|maint|perl)!\*(C'\fR. Any attempt to do so will result in git
603 producing an error like this:
604 .PP
605 .Vb 7
606 \& % git push origin :blead
607 \& *** It is forbidden to delete blead/maint branches in this repository
608 \& error: hooks/update exited with error code 1
609 \& error: hook declined to update refs/heads/blead
610 \& To ssh://perl5.git.perl.org/perl
611 \& ! [remote rejected] blead (hook declined)
612 \& error: failed to push some refs to \*(Aqssh://perl5.git.perl.org/perl\*(Aq
613 .Ve
614 .PP
615 As a matter of policy we do \fBnot\fR edit the history of the blead and
616 maint\-* branches. If a typo (or worse) sneaks into a commit to blead or
617 maint\-*, we\*(Aqll fix it in another commit. The only types of updates
618 allowed on these branches are "fast\-forwards", where all history is
619 preserved.
620 .PP
621 Annotated tags in the canonical perl.git repository will never be
622 deleted or modified. Think long and hard about whether you want to push
623 a local tag to perl.git before doing so. (Pushing simple tags is
624 not allowed.)
625 .SS Grafts
626 .IX Subsection "Grafts"
627 The perl history contains one mistake which was not caught in the
628 conversion: a merge was recorded in the history between blead and
629 maint\-5.10 where no merge actually occurred. Due to the nature of git,
630 this is now impossible to fix in the public repository. You can remove
631 this mis\-merge locally by adding the following line to your
632 \&\f(CW\*(C`.git/info/grafts\*(C'\fR file:
633 .PP
634 .Vb 1
635 \& 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930
636 .Ve
637 .PP
638 It is particularly important to have this graft line if any bisecting
639 is done in the area of the "merge" in question.
640 .SH "WRITE ACCESS TO THE GIT REPOSITORY"
641 .IX Header "WRITE ACCESS TO THE GIT REPOSITORY"
642 Once you have write access, you will need to modify the URL for the
643 origin remote to enable pushing. Edit \fI.git/config\fR with the
644 \&\fBgit\-config\fR\|(1) command:
645 .PP
646 .Vb 1
647 \& % git config remote.origin.url [email protected]:Perl/perl5.git
648 .Ve
649 .PP
650 You can also set up your user name and e\-mail address. Most people do
651 this once globally in their \fI~/.gitconfig\fR by doing something like:
652 .PP
653 .Vb 2
654 \& % git config \-\-global user.name "Ævar Arnfjörð Bjarmason"
655 \& % git config \-\-global user.email [email protected]
656 .Ve
657 .PP
658 However, if you\*(Aqd like to override that just for perl,
659 execute something like the following in \fIperl\fR:
660 .PP
661 .Vb 1
662 \& % git config user.email [email protected]
663 .Ve
664 .PP
665 It is also possible to keep \f(CW\*(C`origin\*(C'\fR as a git remote, and add a new
666 remote for ssh access:
667 .PP
668 .Vb 1
669 \& % git remote add camel [email protected]:Perl/perl5.git
670 .Ve
671 .PP
672 This allows you to update your local repository by pulling from
673 \&\f(CW\*(C`origin\*(C'\fR, which is faster and doesn\*(Aqt require you to authenticate, and
674 to push your changes back with the \f(CW\*(C`camel\*(C'\fR remote:
675 .PP
676 .Vb 2
677 \& % git fetch camel
678 \& % git push camel
679 .Ve
680 .PP
681 The \f(CW\*(C`fetch\*(C'\fR command just updates the \f(CW\*(C`camel\*(C'\fR refs, as the objects
682 themselves should have been fetched when pulling from \f(CW\*(C`origin\*(C'\fR.
683 .SS "Working with GitHub pull requests"
684 .IX Subsection "Working with GitHub pull requests"
685 Pull requests typically originate from outside of the \f(CW\*(C`Perl/perl.git\*(C'\fR
686 repository, so if you want to test or work with it locally a vanilla
687 \&\f(CW\*(C`git fetch\*(C'\fR from the \f(CW\*(C`Perl/perl5.git\*(C'\fR repository won\*(Aqt fetch it.
688 .PP
689 However GitHub does provide a mechanism to fetch a pull request to a
690 local branch. They are available on GitHub remotes under \f(CW\*(C`pull/\*(C'\fR, so
691 you can use \f(CW\*(C`git fetch pull/\fR\f(CIPRID\fR\f(CW/head:\fR\f(CIlocalname\fR\f(CW\*(C'\fR to make a
692 local copy. eg. to fetch pull request 9999 to the local branch
693 \&\f(CW\*(C`local\-branch\-name\*(C'\fR run:
694 .PP
695 .Vb 1
696 \& git fetch origin pull/9999/head:local\-branch\-name
697 .Ve
698 .PP
699 and then:
700 .PP
701 .Vb 1
702 \& git checkout local\-branch\-name
703 .Ve
704 .PP
705 Note: this branch is not rebased on \f(CW\*(C`blead\*(C'\fR, so instead of the
706 checkout above, you might want:
707 .PP
708 .Vb 1
709 \& git rebase origin/blead local\-branch\-name
710 .Ve
711 .PP
712 which rebases \f(CW\*(C`local\-branch\-name\*(C'\fR on \f(CW\*(C`blead\*(C'\fR, and checks it out.
713 .PP
714 Alternatively you can configure the remote to fetch all pull requests
715 as remote\-tracking branches. To do this edit the remote in
716 \&\fI.git/config\fR, for example if your GitHub remote is \f(CW\*(C`origin\*(C'\fR you\*(Aqd
717 have:
718 .PP
719 .Vb 3
720 \& [remote "origin"]
721 \& url = [email protected]:/Perl/perl5.git
722 \& fetch = +refs/heads/*:refs/remotes/origin/*
723 .Ve
724 .PP
725 Add a line to map the remote pull request branches to remote\-tracking
726 branches:
727 .PP
728 .Vb 4
729 \& [remote "origin"]
730 \& url = [email protected]:/Perl/perl5.git
731 \& fetch = +refs/heads/*:refs/remotes/origin/*
732 \& fetch = +refs/pull/*/head:refs/remotes/origin/pull/*
733 .Ve
734 .PP
735 and then do a fetch as normal:
736 .PP
737 .Vb 1
738 \& git fetch origin
739 .Ve
740 .PP
741 This will create a remote\-tracking branch for every pull request, including
742 closed requests.
743 .PP
744 To remove those remote\-tracking branches, remove the line added above
745 and prune:
746 .PP
747 .Vb 1
748 \& git fetch \-p origin # or git remote prune origin
749 .Ve
750 .SS "Accepting a patch"
751 .IX Subsection "Accepting a patch"
752 If you have received a patch file generated using the above section,
753 you should try out the patch.
754 .PP
755 First we need to create a temporary new branch for these changes and
756 switch into it:
757 .PP
758 .Vb 1
759 \& % git checkout \-b experimental
760 .Ve
761 .PP
762 Patches that were formatted by \f(CW\*(C`git format\-patch\*(C'\fR are applied with
763 \&\f(CW\*(C`git am\*(C'\fR:
764 .PP
765 .Vb 2
766 \& % git am 0001\-Rename\-Leon\-Brocard\-to\-Orange\-Brocard.patch
767 \& Applying Rename Leon Brocard to Orange Brocard
768 .Ve
769 .PP
770 Note that some UNIX mail systems can mess with text attachments containing
771 \&\*(AqFrom \*(Aq. This will fix them up:
772 .PP
773 .Vb 2
774 \& % perl \-pi \-e\*(Aqs/^>From /From /\*(Aq \e
775 \& 0001\-Rename\-Leon\-Brocard\-to\-Orange\-Brocard.patch
776 .Ve
777 .PP
778 If just a raw diff is provided, it is also possible use this two\-step
779 process:
780 .PP
781 .Vb 3
782 \& % git apply bugfix.diff
783 \& % git commit \-a \-m "Some fixing" \e
784 \& \-\-author="That Guy <[email protected]>"
785 .Ve
786 .PP
787 Now we can inspect the change:
788 .PP
789 .Vb 4
790 \& % git show HEAD
791 \& commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
792 \& Author: Leon Brocard <[email protected]>
793 \& Date: Fri Dec 19 17:02:59 2008 +0000
794 \&
795 \& Rename Leon Brocard to Orange Brocard
796 \&
797 \& diff \-\-git a/AUTHORS b/AUTHORS
798 \& index 293dd70..722c93e 100644
799 \& \-\-\- a/AUTHORS
800 \& +++ b/AUTHORS
801 \& @@ \-541,7 +541,7 @@ Lars Hecking <[email protected]>
802 \& Laszlo Molnar <[email protected]>
803 \& Leif Huhn <[email protected]>
804 \& Len Johnson <[email protected]>
805 \& \-Leon Brocard <[email protected]>
806 \& +Orange Brocard <[email protected]>
807 \& Les Peters <[email protected]>
808 \& Lesley Binks <[email protected]>
809 \& Lincoln D. Stein <[email protected]>
810 .Ve
811 .PP
812 If you are a committer to Perl and you think the patch is good, you can
813 then merge it into blead then push it out to the main repository:
814 .PP
815 .Vb 3
816 \& % git checkout blead
817 \& % git merge experimental
818 \& % git push origin blead
819 .Ve
820 .PP
821 If you want to delete your temporary branch, you may do so with:
822 .PP
823 .Vb 7
824 \& % git checkout blead
825 \& % git branch \-d experimental
826 \& error: The branch \*(Aqexperimental\*(Aq is not an ancestor of your current
827 \& HEAD. If you are sure you want to delete it, run \*(Aqgit branch \-D
828 \& experimental\*(Aq.
829 \& % git branch \-D experimental
830 \& Deleted branch experimental.
831 .Ve
832 .SS "Committing to blead"
833 .IX Subsection "Committing to blead"
834 The \*(Aqblead\*(Aq branch will become the next production release of Perl.
835 .PP
836 Before pushing \fIany\fR local change to blead, it\*(Aqs incredibly important
837 that you do a few things, lest other committers come after you with
838 pitchforks and torches:
839 .IP \(bu 4
840 Make sure you have a good commit message. See "Commit
841 message" in perlhack for details.
842 .IP \(bu 4
843 Run the test suite. You might not think that one typo fix would break a
844 test file. You\*(Aqd be wrong. Here\*(Aqs an example of where not running the
845 suite caused problems. A patch was submitted that added a couple of
846 tests to an existing \fI.t\fR. It couldn\*(Aqt possibly affect anything else, so
847 no need to test beyond the single affected \fI.t\fR, right? But, the
848 submitter\*(Aqs email address had changed since the last of their
849 submissions, and this caused other tests to fail. Running the test
850 target given in the next item would have caught this problem.
851 .IP \(bu 4
852 If you don\*(Aqt run the full test suite, at least \f(CW\*(C`make test_porting\*(C'\fR.
853 This will run basic sanity checks. To see which sanity checks, have a
854 look in \fIt/porting\fR.
855 .IP \(bu 4
856 If you make any changes that affect miniperl or core routines that have
857 different code paths for miniperl, be sure to run \f(CW\*(C`make minitest\*(C'\fR.
858 This will catch problems that even the full test suite will not catch
859 because it runs a subset of tests under miniperl rather than perl.
860 .SS "On merging and rebasing"
861 .IX Subsection "On merging and rebasing"
862 Simple, one\-off commits pushed to the \*(Aqblead\*(Aq branch should be simple
863 commits that apply cleanly. In other words, you should make sure your
864 work is committed against the current position of blead, so that you can
865 push back to the master repository without merging.
866 .PP
867 Sometimes, blead will move while you\*(Aqre building or testing your
868 changes. When this happens, your push will be rejected with a message
869 like this:
870 .PP
871 .Vb 7
872 \& To ssh://perl5.git.perl.org/perl.git
873 \& ! [rejected] blead \-> blead (non\-fast\-forward)
874 \& error: failed to push some refs to \*(Aqssh://perl5.git.perl.org/perl.git\*(Aq
875 \& To prevent you from losing history, non\-fast\-forward updates were
876 \& rejected Merge the remote changes (e.g. \*(Aqgit pull\*(Aq) before pushing
877 \& again. See the \*(AqNote about fast\-forwards\*(Aq section of \*(Aqgit push \-\-help\*(Aq
878 \& for details.
879 .Ve
880 .PP
881 When this happens, you can just \fIrebase\fR your work against the new
882 position of blead, like this (assuming your remote for the master
883 repository is "p5p"):
884 .PP
885 .Vb 2
886 \& % git fetch p5p
887 \& % git rebase p5p/blead
888 .Ve
889 .PP
890 You will see your commits being re\-applied, and you will then be able to
891 push safely. More information about rebasing can be found in the
892 documentation for the \fBgit\-rebase\fR\|(1) command.
893 .PP
894 For larger sets of commits that only make sense together, or that would
895 benefit from a summary of the set\*(Aqs purpose, you should use a merge
896 commit. You should perform your work on a topic branch, which you should regularly rebase
897 against blead to ensure that your code is not broken by blead moving.
898 When you have finished your work, please perform a final rebase and
899 test. Linear history is something that gets lost with every
900 commit on blead, but a final rebase makes the history linear
901 again, making it easier for future maintainers to see what has
902 happened. Rebase as follows (assuming your work was on the
903 branch \f(CW\*(C`committer/somework\*(C'\fR):
904 .PP
905 .Vb 2
906 \& % git checkout committer/somework
907 \& % git rebase blead
908 .Ve
909 .PP
910 Then you can merge it into master like this:
911 .PP
912 .Vb 3
913 \& % git checkout blead
914 \& % git merge \-\-no\-ff \-\-no\-commit committer/somework
915 \& % git commit \-a
916 .Ve
917 .PP
918 The switches above deserve explanation. \f(CW\*(C`\-\-no\-ff\*(C'\fR indicates that even
919 if all your work can be applied linearly against blead, a merge commit
920 should still be prepared. This ensures that all your work will be shown
921 as a side branch, with all its commits merged into the mainstream blead
922 by the merge commit.
923 .PP
924 \&\f(CW\*(C`\-\-no\-commit\*(C'\fR means that the merge commit will be \fIprepared\fR but not
925 \&\fIcommitted\fR. The commit is then actually performed when you run the
926 next command, which will bring up your editor to describe the commit.
927 Without \f(CW\*(C`\-\-no\-commit\*(C'\fR, the commit would be made with nearly no useful
928 message, which would greatly diminish the value of the merge commit as a
929 placeholder for the work\*(Aqs description.
930 .PP
931 When describing the merge commit, explain the purpose of the branch, and
932 keep in mind that this description will probably be used by the
933 eventual release engineer when reviewing the next perldelta document.
934 .PP
935 If the subsequent \fIpush\fR fails then you must be careful on how you \fIrebase\fR.
936 If you use
937 .PP
938 .Vb 1
939 \& % git rebase p5p/blead
940 .Ve
941 .PP
942 or
943 .PP
944 .Vb 1
945 \& % git pull \-\-rebase
946 .Ve
947 .PP
948 then your carefully created merge commit will be lost! To avoid this you
949 can use:
950 .PP
951 .Vb 2
952 \& % git fetch p5p
953 \& % git rebase \-\-rebase\-merges p5p/blead
954 .Ve
955 .PP
956 This will recreate your merge commit.
957 .PP
958 (Should you be stuck with an older version of git (prior to 2.18), then
959 \&\f(CW\*(C`git rebase\*(C'\fR will not have the \f(CW\*(C`\-\-rebase\-merges\*(C'\fR switch, instead you
960 have to use the \f(CW\*(C`\-\-preserve\-merges\*(C'\fR switch.)
961 .SS "Committing to maintenance versions"
962 .IX Subsection "Committing to maintenance versions"
963 Maintenance versions should only be altered to add critical bug fixes,
964 see perlpolicy.
965 .PP
966 To commit to a maintenance version of perl, you need to create a local
967 tracking branch:
968 .PP
969 .Vb 1
970 \& % git checkout \-\-track \-b maint\-5.005 origin/maint\-5.005
971 .Ve
972 .PP
973 This creates a local branch named \f(CW\*(C`maint\-5.005\*(C'\fR, which tracks the
974 remote branch \f(CW\*(C`origin/maint\-5.005\*(C'\fR. Then you can pull, commit, merge
975 and push as before.
976 .PP
977 You can also cherry\-pick commits from blead and another branch, by
978 using the \f(CW\*(C`git cherry\-pick\*(C'\fR command. It is recommended to use the
979 \&\fB\-x\fR option to \f(CW\*(C`git cherry\-pick\*(C'\fR in order to record the SHA1 of the
980 original commit in the new commit message.
981 .PP
982 Before pushing any change to a maint version, make sure you\*(Aqve
983 satisfied the steps in "Committing to blead" above.
984 .SS "Using a smoke\-me branch to test changes"
985 .IX Subsection "Using a smoke-me branch to test changes"
986 Sometimes a change affects code paths which you cannot test on the OSes
987 which are directly available to you and it would be wise to have users
988 on other OSes test the change before you commit it to blead.
989 .PP
990 Fortunately, there is a way to get your change smoke\-tested on various
991 OSes: push it to a "smoke\-me" branch and wait for certain automated
992 smoke\-testers to report the results from their OSes.
993 A "smoke\-me" branch is identified by the branch name: specifically, as
994 seen on github.com it must be a local branch whose first name
995 component is precisely \f(CW\*(C`smoke\-me\*(C'\fR.
996 .PP
997 The procedure for doing this is roughly as follows (using the example of
998 tonyc\*(Aqs smoke\-me branch called win32stat):
999 .PP
1000 First, make a local branch and switch to it:
1001 .PP
1002 .Vb 1
1003 \& % git checkout \-b win32stat
1004 .Ve
1005 .PP
1006 Make some changes, build perl and test your changes, then commit them to
1007 your local branch. Then push your local branch to a remote smoke\-me
1008 branch:
1009 .PP
1010 .Vb 1
1011 \& % git push origin win32stat:smoke\-me/tonyc/win32stat
1012 .Ve
1013 .PP
1014 Now you can switch back to blead locally:
1015 .PP
1016 .Vb 1
1017 \& % git checkout blead
1018 .Ve
1019 .PP
1020 and continue working on other things while you wait a day or two,
1021 keeping an eye on the results reported for your \f(CW\*(C`smoke\-me\*(C'\fR branch at
1022 <https://perl.develop\-help.com/?b=smoke\-me/tonyc/win32state>.
1023 .PP
1024 If all is well then update your blead branch:
1025 .PP
1026 .Vb 1
1027 \& % git pull
1028 .Ve
1029 .PP
1030 then checkout your smoke\-me branch once more and rebase it on blead:
1031 .PP
1032 .Vb 1
1033 \& % git rebase blead win32stat
1034 .Ve
1035 .PP
1036 Now switch back to blead and merge your smoke\-me branch into it:
1037 .PP
1038 .Vb 2
1039 \& % git checkout blead
1040 \& % git merge win32stat
1041 .Ve
1042 .PP
1043 As described earlier, if there are many changes on your smoke\-me branch
1044 then you should prepare a merge commit in which to give an overview of
1045 those changes by using the following command instead of the last
1046 command above:
1047 .PP
1048 .Vb 1
1049 \& % git merge win32stat \-\-no\-ff \-\-no\-commit
1050 .Ve
1051 .PP
1052 You should now build perl and test your (merged) changes one last time
1053 (ideally run the whole test suite, but failing that at least run the
1054 \&\fIt/porting/*.t\fR tests) before pushing your changes as usual:
1055 .PP
1056 .Vb 1
1057 \& % git push origin blead
1058 .Ve
1059 .PP
1060 Finally, you should then delete the remote smoke\-me branch:
1061 .PP
1062 .Vb 1
1063 \& % git push origin :smoke\-me/tonyc/win32stat
1064 .Ve
1065 .PP
1066 (which is likely to produce a warning like this, which can be ignored:
1067 .PP
1068 .Vb 4
1069 \& remote: fatal: ambiguous argument
1070 \& \*(Aqrefs/heads/smoke\-me/tonyc/win32stat\*(Aq:
1071 \& unknown revision or path not in the working tree.
1072 \& remote: Use \*(Aq\-\-\*(Aq to separate paths from revisions
1073 .Ve
1074 .PP
1075 ) and then delete your local branch:
1076 .PP
1077 .Vb 1
1078 \& % git branch \-d win32stat
1079 .Ve