Debian Codegraph @

upstream/debian-unstable/man1/perlgit.1

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