This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Move more URLs from http:// to https://
[perl5.git] / pod / perlgit.pod
CommitLineData
49781f4a
AB
1=encoding utf8
2
0549aefb
LB
3=for comment
4Consistent formatting of this file is achieved with:
04c692a8 5 perl ./Porting/podtidy pod/perlgit.pod
0549aefb 6
d7dd28b6
LB
7=head1 NAME
8
04c692a8 9perlgit - Detailed information about git and the Perl repository
d7dd28b6 10
04c692a8 11=head1 DESCRIPTION
d7dd28b6 12
04c692a8
DR
13This document provides details on using git to develop Perl. If you are
14just interested in working on a quick patch, see L<perlhack> first.
15This document is intended for people who are regular contributors to
16Perl, including those with write access to the git repository.
184487f0 17
04c692a8 18=head1 CLONING THE REPOSITORY
f6c12373 19
04c692a8
DR
20All of Perl's source code is kept centrally in a Git repository at
21I<perl5.git.perl.org>.
f6c12373 22
04c692a8 23You can make a read-only clone of the repository by running:
f6c12373 24
04c692a8 25 % git clone git://perl5.git.perl.org/perl.git perl
f6c12373 26
04c692a8 27This uses the git protocol (port 9418).
f6c12373 28
04c692a8
DR
29If you cannot use the git protocol for firewall reasons, you can also
30clone via http, though this is much slower:
3482f01a 31
71c89d21 32 % git clone https://perl5.git.perl.org/perl.git perl
b47aa495 33
04c692a8 34=head1 WORKING WITH THE REPOSITORY
d7dd28b6 35
6acba58e 36Once you have changed into the repository directory, you can inspect
04c692a8
DR
37it. After a clone the repository will contain a single local branch,
38which will be the current branch as well, as indicated by the asterisk.
39219fd3
YO
39
40 % git branch
41 * blead
42
f755e97d 43Using the -a switch to C<branch> will also show the remote tracking
6acba58e 44branches in the repository:
39219fd3 45
d9847473 46 % git branch -a
09081495 47 * blead
d7dd28b6
LB
48 origin/HEAD
49 origin/blead
50 ...
51
6acba58e
LB
52The branches that begin with "origin" correspond to the "git remote"
53that you cloned from (which is named "origin"). Each branch on the
c9d1da35 54remote will be exactly tracked by these branches. You should NEVER do
6acba58e
LB
55work on these remote tracking branches. You only ever do work in a
56local branch. Local branches can be configured to automerge (on pull)
57from a designated remote tracking branch. This is the case with the
58default branch C<blead> which will be configured to merge from the
59remote tracking branch C<origin/blead>.
39219fd3 60
d7dd28b6
LB
61You can see recent commits:
62
c2cf2042 63 % git log
d7dd28b6 64
6acba58e
LB
65And pull new changes from the repository, and update your local
66repository (must be clean first)
d7dd28b6
LB
67
68 % git pull
09081495 69
6acba58e
LB
70Assuming we are on the branch C<blead> immediately after a pull, this
71command would be more or less equivalent to:
39219fd3
YO
72
73 % git fetch
74 % git merge origin/blead
75
6acba58e
LB
76In fact if you want to update your local repository without touching
77your working directory you do:
39219fd3
YO
78
79 % git fetch
80
6acba58e
LB
81And if you want to update your remote-tracking branches for all defined
82remotes simultaneously you can do
39219fd3
YO
83
84 % git remote update
85
6acba58e
LB
86Neither of these last two commands will update your working directory,
87however both will update the remote-tracking branches in your
88repository.
39219fd3 89
6051489b
NC
90To make a local branch of a remote branch:
91
92 % git checkout -b maint-5.10 origin/maint-5.10
93
09081495
LB
94To switch back to blead:
95
96 % git checkout blead
c2cf2042 97
ba336be1 98=head2 Finding out your status
39219fd3
YO
99
100The most common git command you will use will probably be
101
102 % git status
103
6acba58e
LB
104This command will produce as output a description of the current state
105of the repository, including modified files and unignored untracked
106files, and in addition it will show things like what files have been
107staged for the next commit, and usually some useful information about
108how to change things. For instance the following:
39219fd3 109
c7956846
KW
110 % git status
111 On branch blead
112 Your branch is ahead of 'origin/blead' by 1 commit.
82217626 113
c7956846
KW
114 Changes to be committed:
115 (use "git reset HEAD <file>..." to unstage)
82217626 116
c7956846 117 modified: pod/perlgit.pod
82217626 118
c7956846
KW
119 Changes not staged for commit:
120 (use "git add <file>..." to update what will be committed)
121 (use "git checkout -- <file>..." to discard changes in working
122 directory)
82217626 123
c7956846 124 modified: pod/perlgit.pod
82217626 125
c7956846
KW
126 Untracked files:
127 (use "git add <file>..." to include in what will be committed)
82217626 128
c7956846 129 deliberate.untracked
39219fd3 130
6acba58e
LB
131This shows that there were changes to this document staged for commit,
132and that there were further changes in the working directory not yet
133staged. It also shows that there was an untracked file in the working
134directory, and as you can see shows how to change all of this. It also
0549aefb 135shows that there is one commit on the working branch C<blead> which has
ff28a605 136not been pushed to the C<origin> remote yet. B<NOTE>: This output
0549aefb
LB
137is also what you see as a template if you do not provide a message to
138C<git commit>.
7f6effc7 139
04c692a8 140=head2 Patch workflow
7f6effc7 141
04c692a8
DR
142First, please read L<perlhack> for details on hacking the Perl core.
143That document covers many details on how to create a good patch.
7f6effc7 144
04c692a8
DR
145If you already have a Perl repository, you should ensure that you're on
146the I<blead> branch, and your repository is up to date:
12322d22
A
147
148 % git checkout blead
149 % git pull
150
6a7cbfe8
LB
151It's preferable to patch against the latest blead version, since this
152is where new development occurs for all changes other than critical bug
04c692a8 153fixes. Critical bug fix patches should be made against the relevant
7f4ffa9d
RS
154maint branches, or should be submitted with a note indicating all the
155branches where the fix should be applied.
a44f43ac 156
6acba58e
LB
157Now that we have everything up to date, we need to create a temporary
158new branch for these changes and switch into it:
b1fccde5 159
a9b05323 160 % git checkout -b orange
23f8d33e 161
a9b05323
YO
162which is the short form of
163
b1fccde5
LB
164 % git branch orange
165 % git checkout orange
166
0c24b290
AB
167Creating a topic branch makes it easier for the maintainers to rebase
168or merge back into the master blead for a more linear history. If you
77db6475
LB
169don't work on a topic branch the maintainer has to manually cherry pick
170your changes onto blead before they can be applied.
0c24b290 171
77db6475 172That'll get you scolded on perl5-porters, so don't do that. Be Awesome.
0c24b290 173
c2cf2042
LB
174Then make your changes. For example, if Leon Brocard changes his name
175to Orange Brocard, we should change his name in the AUTHORS file:
176
177 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
178
179You can see what files are changed:
180
181 % git status
82217626
LM
182 On branch orange
183 Changes to be committed:
184 (use "git reset HEAD <file>..." to unstage)
185
186 modified: AUTHORS
c2cf2042 187
c2cf2042
LB
188And you can see the changes:
189
c7956846
KW
190 % git diff
191 diff --git a/AUTHORS b/AUTHORS
192 index 293dd70..722c93e 100644
193 --- a/AUTHORS
194 +++ b/AUTHORS
195 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
196 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
197 Leif Huhn <leif@hale.dkstat.com>
198 Len Johnson <lenjay@ibm.net>
199 -Leon Brocard <acme@astray.com>
200 +Orange Brocard <acme@astray.com>
201 Les Peters <lpeters@aol.net>
202 Lesley Binks <lesley.binks@gmail.com>
203 Lincoln D. Stein <lstein@cshl.org>
c2cf2042 204
04c692a8 205Now commit your change locally:
77471e41 206
c7956846
KW
207 % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
208 Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
209 1 files changed, 1 insertions(+), 1 deletions(-)
77471e41 210
04c692a8
DR
211The C<-a> option is used to include all files that git tracks that you
212have changed. If at this time, you only want to commit some of the
213files you have worked on, you can omit the C<-a> and use the command
214C<S<git add I<FILE ...>>> before doing the commit. C<S<git add
215--interactive>> allows you to even just commit portions of files
216instead of all the changes in them.
77471e41 217
04c692a8
DR
218The C<-m> option is used to specify the commit message. If you omit it,
219git will open a text editor for you to compose the message
220interactively. This is useful when the changes are more complex than
221the sample given here, and, depending on the editor, to know that the
222first line of the commit message doesn't exceed the 50 character legal
223maximum.
77471e41 224
04c692a8
DR
225Once you've finished writing your commit message and exited your
226editor, git will write your change to disk and tell you something like
227this:
77471e41 228
c7956846
KW
229 Created commit daf8e63: explain git status and stuff about remotes
230 1 files changed, 83 insertions(+), 3 deletions(-)
c2cf2042 231
04c692a8 232If you re-run C<git status>, you should see something like this:
c2cf2042 233
c7956846
KW
234 % git status
235 On branch orange
236 Untracked files:
237 (use "git add <file>..." to include in what will be committed)
82217626 238
c7956846 239 deliberate.untracked
82217626 240
c7956846
KW
241 nothing added to commit but untracked files present (use "git add" to
242 track)
2be70973 243
04c692a8
DR
244When in doubt, before you do anything else, check your status and read
245it carefully, many questions are answered directly by the git status
246output.
2be70973 247
dc3c3040
GA
248You can examine your last commit with:
249
250 % git show HEAD
251
252and if you are not happy with either the description or the patch
c26da522 253itself you can fix it up by editing the files once more and then issue:
dc3c3040
GA
254
255 % git commit -a --amend
256
c2cf2042
LB
257Now you should create a patch file for all your local changes:
258
5df24413 259 % git format-patch -M blead..
c2cf2042
LB
260 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
261
9420b3b3
TC
262Or for a lot of changes, e.g. from a topic branch:
263
5df24413 264 % git format-patch --stdout -M blead.. > topic-branch-changes.patch
9420b3b3 265
e001c712 266You should now send an email to
dce3ee48
AB
267L<perlbug@perl.org|mailto:perlbug@perl.org> with a description of your
268changes, and include this patch file as an attachment. In addition to
77db6475 269being tracked by RT, mail to perlbug will automatically be forwarded to
04c692a8
DR
270perl5-porters (with manual moderation, so please be patient). You
271should only send patches to
272L<perl5-porters@perl.org|mailto:perl5-porters@perl.org> directly if the
273patch is not ready to be applied, but intended for discussion.
64a8e22b 274
c9815633
DB
275Please do not use git-send-email(1) to send your patch. See L<Sending
276patch emails|/Sending patch emails> for more information.
c2cf2042 277
b1fccde5
LB
278If you want to delete your temporary branch, you may do so with:
279
c7956846
KW
280 % git checkout blead
281 % git branch -d orange
282 error: The branch 'orange' is not an ancestor of your current HEAD.
283 If you are sure you want to delete it, run 'git branch -D orange'.
284 % git branch -D orange
285 Deleted branch orange.
7df2e4bc 286
04c692a8
DR
287=head2 Committing your changes
288
6a6d7b97 289Assuming that you'd like to commit all the changes you've made as a
04c692a8
DR
290single atomic unit, run this command:
291
cc116ce7 292 % git commit -a
04c692a8
DR
293
294(That C<-a> tells git to add every file you've changed to this commit.
295New files aren't automatically added to your commit when you use
296C<commit -a> If you want to add files or to commit some, but not all of
297your changes, have a look at the documentation for C<git add>.)
298
299Git will start up your favorite text editor, so that you can craft a
300commit message for your change. See L<perlhack/Commit message> for more
301information about what makes a good commit message.
302
303Once you've finished writing your commit message and exited your
304editor, git will write your change to disk and tell you something like
305this:
306
c7956846
KW
307 Created commit daf8e63: explain git status and stuff about remotes
308 1 files changed, 83 insertions(+), 3 deletions(-)
04c692a8
DR
309
310If you re-run C<git status>, you should see something like this:
311
c7956846
KW
312 % git status
313 On branch blead
314 Your branch is ahead of 'origin/blead' by 2 commits.
315 (use "git push" to publish your local commits)
316 Untracked files:
317 (use "git add <file>..." to include in what will be committed)
82217626 318
c7956846 319 deliberate.untracked
82217626 320
c7956846
KW
321 nothing added to commit but untracked files present (use "git add" to
322 track)
04c692a8
DR
323
324When in doubt, before you do anything else, check your status and read
325it carefully, many questions are answered directly by the git status
326output.
327
9420b3b3
TC
328=head2 Sending patch emails
329
11fa7e22
LM
330After you've generated your patch you should send it
331to L<perlbug@perl.org|mailto:perlbug@perl.org> (as discussed L<in the
332previous section|/"Patch workflow">) with a normal mail client as an
9420b3b3
TC
333attachment, along with a description of the patch.
334
335You B<must not> use git-send-email(1) to send patches generated with
336git-format-patch(1). The RT ticketing system living behind
11fa7e22
LM
337L<perlbug@perl.org|mailto:perlbug@perl.org> does not respect the inline
338contents of E-Mails, sending an inline patch to RT guarantees that your
339patch will be destroyed.
9420b3b3
TC
340
341Someone may download your patch from RT, which will result in the
11fa7e22
LM
342subject (the first line of the commit message) being omitted. See
343L<RT #74192|https://rt.perl.org/Ticket/Display.html?id=74192> and
71c89d21 344L<commit a4583001|https://perl5.git.perl.org/perl.git/commitdiff/a4583001>
11fa7e22 345for an example. Alternatively someone may
9420b3b3 346apply your patch from RT after it arrived in their mailbox, by which
11fa7e22
LM
347time RT will have modified the inline content of the message. See
348L<RT #74532|https://rt.perl.org/Ticket/Display.html?id=74532> and
71c89d21 349L<commit f9bcfeac|https://perl5.git.perl.org/perl.git/commitdiff/f9bcfeac>
11fa7e22 350for a bad example of this failure mode.
2d5f1d01 351
a44f43ac
RGS
352=head2 A note on derived files
353
354Be aware that many files in the distribution are derivative--avoid
0549aefb 355patching them, because git won't see the changes to them, and the build
04c692a8 356process will overwrite them. Patch the originals instead. Most
0549aefb 357utilities (like perldoc) are in this category, i.e. patch
77db6475 358F<utils/perldoc.PL> rather than F<utils/perldoc>. Similarly, don't
11fa7e22
LM
359create patches for files under F<$src_root/ext> from their copies found
360in F<$install_root/lib>. If you are unsure about the proper location of
361a file that may have gotten copied while building the source
362distribution, consult the F<MANIFEST>.
a44f43ac 363
04c692a8 364=head2 Cleaning a working directory
b0d36535 365
6acba58e 366The command C<git clean> can with varying arguments be used as a
dc3c3040 367replacement for C<make clean>.
b0d36535
YO
368
369To reset your working directory to a pristine condition you can do:
370
e0b2b458 371 % git clean -dxf
b0d36535
YO
372
373However, be aware this will delete ALL untracked content. You can use
374
e0b2b458 375 % git clean -Xf
b0d36535 376
6acba58e 377to remove all ignored untracked files, such as build and test
11fa7e22 378byproduct, but leave any manually created files alone.
b0d36535 379
0549aefb 380If you only want to cancel some uncommitted edits, you can use C<git
c26da522
LB
381checkout> and give it a list of files to be reverted, or C<git checkout
382-f> to revert them all.
f755e97d
RGS
383
384If you want to cancel one or several commits, you can use C<git reset>.
385
04c692a8 386=head2 Bisecting
d82a90c1 387
5b9539f4
NC
388C<git> provides a built-in way to determine which commit should be blamed
389for introducing a given bug. C<git bisect> performs a binary search of
390history to locate the first failing commit. It is fast, powerful and
391flexible, but requires some setup and to automate the process an auxiliary
392shell script is needed.
393
394The core provides a wrapper program, F<Porting/bisect.pl>, which attempts to
395simplify as much as possible, making bisecting as simple as running a Perl
396one-liner. For example, if you want to know when this became an error:
397
398 perl -e 'my $a := 2'
399
400you simply run this:
401
402 .../Porting/bisect.pl -e 'my $a := 2;'
403
11fa7e22
LM
404Using F<Porting/bisect.pl>, with one command (and no other files) it's easy to
405find out
5b9539f4
NC
406
407=over 4
408
409=item *
410
411Which commit caused this example code to break?
412
413=item *
414
415Which commit caused this example code to start working?
416
417=item *
418
419Which commit added the first file to match this regex?
420
421=item *
422
423Which commit removed the last file to match this regex?
424
425=back
426
427usually without needing to know which versions of perl to use as start and
11fa7e22
LM
428end revisions, as F<Porting/bisect.pl> automatically searches to find the
429earliest stable version for which the test case passes. Run
5b9539f4
NC
430C<Porting/bisect.pl --help> for the full documentation, including how to
431set the C<Configure> and build time options.
432
433If you require more flexibility than F<Porting/bisect.pl> has to offer, you'll
434need to run C<git bisect> yourself. It's most useful to use C<git bisect run>
435to automate the building and testing of perl revisions. For this you'll need
436a shell script for C<git> to call to test a particular revision. An example
437script is F<Porting/bisect-example.sh>, which you should copy B<outside> of
438the repository, as the bisect process will reset the state to a clean checkout
439as it runs. The instructions below assume that you copied it as F<~/run> and
440then edited it as appropriate.
d82a90c1 441
bdaf0bc6 442You first enter in bisect mode with:
d82a90c1
VP
443
444 % git bisect start
445
6acba58e
LB
446For example, if the bug is present on C<HEAD> but wasn't in 5.10.0,
447C<git> will learn about this when you enter:
d82a90c1
VP
448
449 % git bisect bad
450 % git bisect good perl-5.10.0
451 Bisecting: 853 revisions left to test after this
452
6acba58e 453This results in checking out the median commit between C<HEAD> and
bdaf0bc6 454C<perl-5.10.0>. You can then run the bisecting process with:
d82a90c1
VP
455
456 % git bisect run ~/run
457
458When the first bad commit is isolated, C<git bisect> will tell you so:
459
460 ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
461 commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
462 Author: Dave Mitchell <davem@fdisolutions.com>
463 Date: Sat Feb 9 14:56:23 2008 +0000
464
9469eb4a 465 [perl #49472] Attributes + Unknown Error
d82a90c1
VP
466 ...
467
468 bisect run success
469
6acba58e
LB
470You can peek into the bisecting process with C<git bisect log> and
471C<git bisect visualize>. C<git bisect reset> will get you out of bisect
472mode.
d82a90c1 473
6acba58e
LB
474Please note that the first C<good> state must be an ancestor of the
475first C<bad> state. If you want to search for the commit that I<solved>
476some bug, you have to negate your test case (i.e. exit with C<1> if OK
477and C<0> if not) and still mark the lower bound as C<good> and the
478upper as C<bad>. The "first bad commit" has then to be understood as
479the "first commit where the bug is solved".
d82a90c1 480
6acba58e
LB
481C<git help bisect> has much more information on how you can tweak your
482binary searches.
feb5e972 483
ca31f56c
JK
484Following bisection you may wish to configure, build and test perl at
485commits identified by the bisection process. Sometimes, particularly
486with older perls, C<make> may fail during this process. In this case
487you may be able to patch the source code at the older commit point. To
488do so, please follow the suggestions provided in
489L<perlhack/Building perl at older commits>.
490
99cd8e46 491=head2 Topic branches and rewriting history
9d68b7ed 492
04c692a8 493Individual committers should create topic branches under
04edae75 494B<yourname>/B<some_descriptive_name>:
03050721 495
ff28a605
LM
496 % branch="$yourname/$some_descriptive_name"
497 % git checkout -b $branch
04edae75 498 ... do local edits, commits etc ...
ff28a605 499 % git push origin -u $branch
03050721 500
04edae75
AP
501Should you be stuck with an ancient version of git (prior to 1.7), then
502C<git push> will not have the C<-u> switch, and you have to replace the
503last step with the following sequence:
504
ff28a605
LM
505 % git push origin $branch:refs/heads/$branch
506 % git config branch.$branch.remote origin
507 % git config branch.$branch.merge refs/heads/$branch
04edae75
AP
508
509If you want to make changes to someone else's topic branch, you should
510check with its creator before making any change to it.
511
512You
04c692a8
DR
513might sometimes find that the original author has edited the branch's
514history. There are lots of good reasons for this. Sometimes, an author
515might simply be rebasing the branch onto a newer source point.
516Sometimes, an author might have found an error in an early commit which
517they wanted to fix before merging the branch to blead.
c26da522 518
04c692a8
DR
519Currently the master repository is configured to forbid
520non-fast-forward merges. This means that the branches within can not be
521rebased and pushed as a single step.
c26da522 522
04c692a8
DR
523The only way you will ever be allowed to rebase or modify the history
524of a pushed branch is to delete it and push it as a new branch under
525the same name. Please think carefully about doing this. It may be
526better to sequentially rename your branches so that it is easier for
527others working with you to cherry-pick their local changes onto the new
528version. (XXX: needs explanation).
c26da522 529
04c692a8
DR
530If you want to rebase a personal topic branch, you will have to delete
531your existing topic branch and push as a new version of it. You can do
532this via the following formula (see the explanation about C<refspec>'s
533in the git push documentation for details) after you have rebased your
534branch:
c26da522 535
cc116ce7 536 # first rebase
ff28a605
LM
537 % git checkout $user/$topic
538 % git fetch
539 % git rebase origin/blead
c26da522 540
cc116ce7 541 # then "delete-and-push"
ff28a605
LM
542 % git push origin :$user/$topic
543 % git push origin $user/$topic
c26da522 544
04c692a8
DR
545B<NOTE:> it is forbidden at the repository level to delete any of the
546"primary" branches. That is any branch matching
547C<m!^(blead|maint|perl)!>. Any attempt to do so will result in git
548producing an error like this:
c26da522 549
ff28a605 550 % git push origin :blead
cc116ce7
AP
551 *** It is forbidden to delete blead/maint branches in this repository
552 error: hooks/update exited with error code 1
553 error: hook declined to update refs/heads/blead
554 To ssh://perl5.git.perl.org/perl
555 ! [remote rejected] blead (hook declined)
556 error: failed to push some refs to 'ssh://perl5.git.perl.org/perl'
c26da522 557
04c692a8
DR
558As a matter of policy we do B<not> edit the history of the blead and
559maint-* branches. If a typo (or worse) sneaks into a commit to blead or
560maint-*, we'll fix it in another commit. The only types of updates
e7f1d4a7 561allowed on these branches are "fast-forwards", where all history is
04c692a8 562preserved.
2bab0636 563
04c692a8
DR
564Annotated tags in the canonical perl.git repository will never be
565deleted or modified. Think long and hard about whether you want to push
e7f1d4a7 566a local tag to perl.git before doing so. (Pushing simple tags is
04c692a8 567not allowed.)
2bab0636 568
feb5e972 569=head2 Grafts
c26da522 570
04c692a8
DR
571The perl history contains one mistake which was not caught in the
572conversion: a merge was recorded in the history between blead and
573maint-5.10 where no merge actually occurred. Due to the nature of git,
574this is now impossible to fix in the public repository. You can remove
575this mis-merge locally by adding the following line to your
576C<.git/info/grafts> file:
c26da522 577
c7956846 578 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930
c26da522 579
04c692a8
DR
580It is particularly important to have this graft line if any bisecting
581is done in the area of the "merge" in question.
ce2a8773 582
04c692a8
DR
583=head1 WRITE ACCESS TO THE GIT REPOSITORY
584
585Once you have write access, you will need to modify the URL for the
586origin remote to enable pushing. Edit F<.git/config> with the
587git-config(1) command:
588
589 % git config remote.origin.url ssh://perl5.git.perl.org/perl.git
590
591You can also set up your user name and e-mail address. Most people do
592this once globally in their F<~/.gitconfig> by doing something like:
593
594 % git config --global user.name "Ævar Arnfjörð Bjarmason"
595 % git config --global user.email avarab@gmail.com
596
ff28a605 597However, if you'd like to override that just for perl,
04c692a8
DR
598execute something like the following in F<perl>:
599
600 % git config user.email avar@cpan.org
601
602It is also possible to keep C<origin> as a git remote, and add a new
603remote for ssh access:
604
605 % git remote add camel perl5.git.perl.org:/perl.git
606
607This allows you to update your local repository by pulling from
608C<origin>, which is faster and doesn't require you to authenticate, and
609to push your changes back with the C<camel> remote:
610
611 % git fetch camel
612 % git push camel
613
614The C<fetch> command just updates the C<camel> refs, as the objects
615themselves should have been fetched when pulling from C<origin>.
04baf1ff 616
99cd8e46 617=head2 Accepting a patch
04c692a8
DR
618
619If you have received a patch file generated using the above section,
620you should try out the patch.
621
622First we need to create a temporary new branch for these changes and
623switch into it:
624
c7956846 625 % git checkout -b experimental
04c692a8
DR
626
627Patches that were formatted by C<git format-patch> are applied with
628C<git am>:
629
c7956846
KW
630 % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
631 Applying Rename Leon Brocard to Orange Brocard
04c692a8 632
6fc2106e
DM
633Note that some UNIX mail systems can mess with text attachments containing
634'From '. This will fix them up:
635
c7956846
KW
636 % perl -pi -e's/^>From /From /' \
637 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
6fc2106e 638
04c692a8
DR
639If just a raw diff is provided, it is also possible use this two-step
640process:
641
11fa7e22 642 % git apply bugfix.diff
a98780ae
KW
643 % git commit -a -m "Some fixing" \
644 --author="That Guy <that.guy@internets.com>"
edcf105d 645
04c692a8
DR
646Now we can inspect the change:
647
c7956846
KW
648 % git show HEAD
649 commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
650 Author: Leon Brocard <acme@astray.com>
651 Date: Fri Dec 19 17:02:59 2008 +0000
652
653 Rename Leon Brocard to Orange Brocard
654
655 diff --git a/AUTHORS b/AUTHORS
656 index 293dd70..722c93e 100644
657 --- a/AUTHORS
658 +++ b/AUTHORS
659 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
660 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
661 Leif Huhn <leif@hale.dkstat.com>
662 Len Johnson <lenjay@ibm.net>
663 -Leon Brocard <acme@astray.com>
664 +Orange Brocard <acme@astray.com>
665 Les Peters <lpeters@aol.net>
666 Lesley Binks <lesley.binks@gmail.com>
667 Lincoln D. Stein <lstein@cshl.org>
04c692a8
DR
668
669If you are a committer to Perl and you think the patch is good, you can
670then merge it into blead then push it out to the main repository:
671
672 % git checkout blead
673 % git merge experimental
68382b67 674 % git push origin blead
04c692a8
DR
675
676If you want to delete your temporary branch, you may do so with:
677
c7956846
KW
678 % git checkout blead
679 % git branch -d experimental
680 error: The branch 'experimental' is not an ancestor of your current
681 HEAD. If you are sure you want to delete it, run 'git branch -D
682 experimental'.
683 % git branch -D experimental
684 Deleted branch experimental.
04c692a8
DR
685
686=head2 Committing to blead
687
688The 'blead' branch will become the next production release of Perl.
edcf105d
JV
689
690Before pushing I<any> local change to blead, it's incredibly important
691that you do a few things, lest other committers come after you with
692pitchforks and torches:
693
694=over
695
696=item *
697
04c692a8
DR
698Make sure you have a good commit message. See L<perlhack/Commit
699message> for details.
edcf105d
JV
700
701=item *
702
04c692a8
DR
703Run the test suite. You might not think that one typo fix would break a
704test file. You'd be wrong. Here's an example of where not running the
705suite caused problems. A patch was submitted that added a couple of
11fa7e22
LM
706tests to an existing F<.t>. It couldn't possibly affect anything else, so
707no need to test beyond the single affected F<.t>, right? But, the
f76a37ee 708submitter's email address had changed since the last of their
04c692a8 709submissions, and this caused other tests to fail. Running the test
f76a37ee 710target given in the next item would have caught this problem.
edcf105d
JV
711
712=item *
713
714If you don't run the full test suite, at least C<make test_porting>.
715This will run basic sanity checks. To see which sanity checks, have a
716look in F<t/porting>.
717
cd78e84f
CB
718=item *
719
720If you make any changes that affect miniperl or core routines that have
04baf1ff 721different code paths for miniperl, be sure to run C<make minitest>.
cd78e84f
CB
722This will catch problems that even the full test suite will not catch
723because it runs a subset of tests under miniperl rather than perl.
724
edcf105d
JV
725=back
726
99cd8e46 727=head2 On merging and rebasing
961bfa8c
RS
728
729Simple, one-off commits pushed to the 'blead' branch should be simple
730commits that apply cleanly. In other words, you should make sure your
731work is committed against the current position of blead, so that you can
732push back to the master repository without merging.
733
734Sometimes, blead will move while you're building or testing your
735changes. When this happens, your push will be rejected with a message
736like this:
737
c7956846
KW
738 To ssh://perl5.git.perl.org/perl.git
739 ! [rejected] blead -> blead (non-fast-forward)
740 error: failed to push some refs to 'ssh://perl5.git.perl.org/perl.git'
741 To prevent you from losing history, non-fast-forward updates were
742 rejected Merge the remote changes (e.g. 'git pull') before pushing
743 again. See the 'Note about fast-forwards' section of 'git push --help'
744 for details.
961bfa8c
RS
745
746When this happens, you can just I<rebase> your work against the new
747position of blead, like this (assuming your remote for the master
748repository is "p5p"):
749
ff28a605
LM
750 % git fetch p5p
751 % git rebase p5p/blead
961bfa8c
RS
752
753You will see your commits being re-applied, and you will then be able to
c9d1da35 754push safely. More information about rebasing can be found in the
961bfa8c
RS
755documentation for the git-rebase(1) command.
756
757For larger sets of commits that only make sense together, or that would
758benefit from a summary of the set's purpose, you should use a merge
759commit. You should perform your work on a L<topic branch|/Topic
760branches and rewriting history>, which you should regularly rebase
761against blead to ensure that your code is not broken by blead moving.
bd3355a0
FC
762When you have finished your work, please perform a final rebase and
763test. Linear history is something that gets lost with every
764commit on blead, but a final rebase makes the history linear
765again, making it easier for future maintainers to see what has
766happened. Rebase as follows (assuming your work was on the
688cbe00 767branch C<< committer/somework >>):
961bfa8c 768
ff28a605
LM
769 % git checkout committer/somework
770 % git rebase blead
bd3355a0
FC
771
772Then you can merge it into master like this:
773
ff28a605
LM
774 % git checkout blead
775 % git merge --no-ff --no-commit committer/somework
776 % git commit -a
961bfa8c
RS
777
778The switches above deserve explanation. C<--no-ff> indicates that even
779if all your work can be applied linearly against blead, a merge commit
780should still be prepared. This ensures that all your work will be shown
781as a side branch, with all its commits merged into the mainstream blead
782by the merge commit.
783
784C<--no-commit> means that the merge commit will be I<prepared> but not
785I<committed>. The commit is then actually performed when you run the
786next command, which will bring up your editor to describe the commit.
787Without C<--no-commit>, the commit would be made with nearly no useful
788message, which would greatly diminish the value of the merge commit as a
789placeholder for the work's description.
790
791When describing the merge commit, explain the purpose of the branch, and
792keep in mind that this description will probably be used by the
793eventual release engineer when reviewing the next perldelta document.
794
04c692a8 795=head2 Committing to maintenance versions
9d68b7ed 796
77db6475
LB
797Maintenance versions should only be altered to add critical bug fixes,
798see L<perlpolicy>.
7f4ffa9d 799
9d68b7ed
LB
800To commit to a maintenance version of perl, you need to create a local
801tracking branch:
802
803 % git checkout --track -b maint-5.005 origin/maint-5.005
804
0549aefb
LB
805This creates a local branch named C<maint-5.005>, which tracks the
806remote branch C<origin/maint-5.005>. Then you can pull, commit, merge
807and push as before.
b0d36535 808
f755e97d 809You can also cherry-pick commits from blead and another branch, by
0549aefb
LB
810using the C<git cherry-pick> command. It is recommended to use the
811B<-x> option to C<git cherry-pick> in order to record the SHA1 of the
812original commit in the new commit message.
f755e97d 813
04c692a8
DR
814Before pushing any change to a maint version, make sure you've
815satisfied the steps in L</Committing to blead> above.
edcf105d 816
04c692a8 817=head2 Merging from a branch via GitHub
bdaf0bc6 818
04c692a8
DR
819While we don't encourage the submission of patches via GitHub, that
820will still happen. Here is a guide to merging patches from a GitHub
821repository.
bdaf0bc6 822
04c692a8
DR
823 % git remote add avar git://github.com/avar/perl.git
824 % git fetch avar
041325d6 825
04c692a8 826Now you can see the differences between the branch and blead:
705c800c 827
04c692a8 828 % git diff avar/orange
705c800c 829
04c692a8 830And you can see the commits:
041325d6 831
04c692a8 832 % git log avar/orange
f755e97d 833
04c692a8
DR
834If you approve of a specific commit, you can cherry pick it:
835
836 % git cherry-pick 0c24b290ae02b2ab3304f51d5e11e85eb3659eae
837
838Or you could just merge the whole branch if you like it all:
839
840 % git merge avar/orange
841
842And then push back to the repository:
843
68382b67 844 % git push origin blead
04c692a8 845
3afc3118
SH
846=head2 Using a smoke-me branch to test changes
847
848Sometimes a change affects code paths which you cannot test on the OSes
849which are directly available to you and it would be wise to have users
850on other OSes test the change before you commit it to blead.
851
852Fortunately, there is a way to get your change smoke-tested on various
853OSes: push it to a "smoke-me" branch and wait for certain automated
854smoke-testers to report the results from their OSes.
9b91093d
Z
855A "smoke-me" branch is identified by the branch name: specifically, as
856seen on perl5.git.perl.org it must be a local branch whose first name
857component is precisely C<smoke-me>.
3afc3118
SH
858
859The procedure for doing this is roughly as follows (using the example of
860of tonyc's smoke-me branch called win32stat):
861
862First, make a local branch and switch to it:
863
864 % git checkout -b win32stat
865
866Make some changes, build perl and test your changes, then commit them to
867your local branch. Then push your local branch to a remote smoke-me
868branch:
869
870 % git push origin win32stat:smoke-me/tonyc/win32stat
871
872Now you can switch back to blead locally:
873
874 % git checkout blead
875
876and continue working on other things while you wait a day or two,
877keeping an eye on the results reported for your smoke-me branch at
878L<http://perl.develop-help.com/?b=smoke-me/tonyc/win32state>.
879
880If all is well then update your blead branch:
881
882 % git pull
883
884then checkout your smoke-me branch once more and rebase it on blead:
885
886 % git rebase blead win32stat
887
888Now switch back to blead and merge your smoke-me branch into it:
889
890 % git checkout blead
891 % git merge win32stat
892
893As described earlier, if there are many changes on your smoke-me branch
894then you should prepare a merge commit in which to give an overview of
895those changes by using the following command instead of the last
896command above:
897
898 % git merge win32stat --no-ff --no-commit
899
900You should now build perl and test your (merged) changes one last time
901(ideally run the whole test suite, but failing that at least run the
902F<t/porting/*.t> tests) before pushing your changes as usual:
903
904 % git push origin blead
905
906Finally, you should then delete the remote smoke-me branch:
907
908 % git push origin :smoke-me/tonyc/win32stat
909
910(which is likely to produce a warning like this, which can be ignored:
911
c7956846
KW
912 remote: fatal: ambiguous argument
913 'refs/heads/smoke-me/tonyc/win32stat':
914 unknown revision or path not in the working tree.
915 remote: Use '--' to separate paths from revisions
3afc3118
SH
916
917) and then delete your local branch:
918
919 % git branch -d win32stat
920
04c692a8
DR
921=head2 A note on camel and dromedary
922
923The committers have SSH access to the two servers that serve
924C<perl5.git.perl.org>. One is C<perl5.git.perl.org> itself (I<camel>),
925which is the 'master' repository. The second one is
926C<users.perl5.git.perl.org> (I<dromedary>), which can be used for
927general testing and development. Dromedary syncs the git tree from
928camel every few minutes, you should not push there. Both machines also
11fa7e22
LM
929have a full CPAN mirror in F</srv/CPAN>, please use this. To share files
930with the general public, dromedary serves your F<~/public_html/> as
71c89d21 931C<L<https://users.perl5.git.perl.org/~yourlogin/>>
04c692a8
DR
932
933These hosts have fairly strict firewalls to the outside. Outgoing, only
934rsync, ssh and git are allowed. For http and ftp, you can use
4b05bc8e 935L<http://webproxy:3128> as proxy. Incoming, the firewall tries to detect
04c692a8
DR
936attacks and blocks IP addresses with suspicious activity. This
937sometimes (but very rarely) has false positives and you might get
938blocked. The quickest way to get unblocked is to notify the admins.
939
940These two boxes are owned, hosted, and operated by booking.com. You can
941reach the sysadmins in #p5p on irc.perl.org or via mail to
11fa7e22 942L<perl5-porters@perl.org|mailto:perl5-porters@perl.org>.