This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Clarify that mail to perlbug also goes to p5p
[perl5.git] / pod / perlrepository.pod
CommitLineData
49781f4a
AB
1=encoding utf8
2
0549aefb
LB
3=for comment
4Consistent formatting of this file is achieved with:
5 perl ./Porting/podtidy pod/perlrepository.pod
6
d7dd28b6
LB
7=head1 NAME
8
9perlrepository - Using the Perl source repository
10
11=head1 SYNOPSIS
12
dc3c3040 13All of Perl's source code is kept centrally in a Git repository at
c26da522
LB
14I<perl5.git.perl.org>. The repository contains many Perl revisions from
15Perl 1 onwards and all the revisions from Perforce, the version control
16system we were using previously. This repository is accessible in
17different ways.
d7dd28b6
LB
18
19The full repository takes up about 80MB of disk space. A check out of
7f4ffa9d 20the blead branch (that is, the main development branch, which contains
6a7cbfe8
LB
21bleadperl, the development version of perl 5) takes up about 160MB of
22disk space (including the repository). A build of bleadperl takes up
23about 200MB (including the repository and the check out).
d7dd28b6 24
ba336be1 25=head1 Getting access to the repository
d7dd28b6 26
ba336be1 27=head2 Read access via the web
d7dd28b6 28
dc3c3040
GA
29You may access the repository over the web. This allows you to browse
30the tree, see recent commits, subscribe to RSS feeds for the changes,
31search for particular commits and more. You may access it at:
d7dd28b6
LB
32
33 http://perl5.git.perl.org/perl.git
34
dc3c3040
GA
35A mirror of the repository is found at:
36
45b194c5 37 http://github.com/mirrors/perl
dc3c3040 38
ba336be1 39=head2 Read access via Git
d7dd28b6
LB
40
41You will need a copy of Git for your computer. You can fetch a copy of
42the repository using the Git protocol (which uses port 9418):
43
e0b2b458 44 % git clone git://perl5.git.perl.org/perl.git perl-git
d7dd28b6 45
f755e97d 46This clones the repository and makes a local copy in the F<perl-git>
d7dd28b6
LB
47directory.
48
49If your local network does not allow you to use port 9418, then you can
cf5e7595 50fetch a copy of the repository over HTTP (this is at least 4x slower):
d7dd28b6 51
e0b2b458 52 % git clone http://perl5.git.perl.org/perl.git perl-http
d7dd28b6 53
f755e97d 54This clones the repository and makes a local copy in the F<perl-http>
d7dd28b6
LB
55directory.
56
ba336be1 57=head2 Write access to the repository
d7dd28b6 58
6acba58e
LB
59If you are a committer, then you can fetch a copy of the repository
60that you can push back on with:
d7dd28b6 61
e0b2b458 62 % git clone ssh://perl5.git.perl.org/perl.git perl-ssh
d7dd28b6 63
8f718e95 64This clones the repository and makes a local copy in the F<perl-ssh>
d7dd28b6
LB
65directory.
66
c26da522 67If you cloned using the git protocol, which is faster than ssh, then
11ed6e28 68you will need to modify the URL for the origin remote to enable
705c800c 69pushing. To do that edit F<.git/config> with git-config(1) like
11ed6e28 70this:
1a0f15d5 71
e0b2b458 72 % git config remote.origin.url ssh://perl5.git.perl.org/perl.git
d7dd28b6 73
9d77ce3f
AB
74You can also set up your user name and e-mail address. Most people do
75this once globally in their F<~/.gitconfig> by doing something like:
184487f0 76
9d77ce3f
AB
77 % git config --global user.name "Ævar Arnfjörð Bjarmason"
78 % git config --global user.email avarab@gmail.com
79
80However if you'd like to override that just for perl then execute then
81execute something like the following in F<perl-git>:
82
83 % git config user.email avar@cpan.org
184487f0 84
6acba58e
LB
85It is also possible to keep C<origin> as a git remote, and add a new
86remote for ssh access:
f6c12373 87
dc3c3040 88 % git remote add camel perl5.git.perl.org:/perl.git
f6c12373 89
6acba58e 90This allows you to update your local repository by pulling from
f755e97d 91C<origin>, which is faster and doesn't require you to authenticate, and
6acba58e 92to push your changes back with the C<camel> remote:
f6c12373
VP
93
94 % git fetch camel
95 % git push camel
96
6acba58e
LB
97The C<fetch> command just updates the C<camel> refs, as the objects
98themselves should have been fetched when pulling from C<origin>.
f6c12373 99
ba336be1 100=head2 A note on camel and dromedary
3482f01a
DK
101
102The committers have SSH access to the two servers that serve
333f8875
VP
103C<perl5.git.perl.org>. One is C<perl5.git.perl.org> itself (I<camel>),
104which is the 'master' repository. The second one is
105C<users.perl5.git.perl.org> (I<dromedary>), which can be used for
106general testing and development. Dromedary syncs the git tree from
107camel every few minutes, you should not push there. Both machines also
3482f01a
DK
108have a full CPAN mirror in /srv/CPAN, please use this. To share files
109with the general public, dromedary serves your ~/public_html/ as
333f8875 110C<http://users.perl5.git.perl.org/~yourlogin/>
b47aa495 111
3482f01a
DK
112These hosts have fairly strict firewalls to the outside. Outgoing, only
113rsync, ssh and git are allowed. For http and ftp, you can use
114http://webproxy:3128 as proxy. Incoming, the firewall tries to detect
115attacks and blocks IP addresses with suspicious activity. This
116sometimes (but very rarely) has false positives and you might get
117blocked. The quickest way to get unblocked is to notify the admins.
118
119These two boxes are owned, hosted, and operated by booking.com. You can
120reach the sysadmins in #p5p on irc.perl.org or via mail to
121C<perl5-porters@perl.org>
122
ba336be1 123=head1 Overview of the repository
d7dd28b6 124
6acba58e
LB
125Once you have changed into the repository directory, you can inspect
126it.
d7dd28b6 127
39219fd3 128After a clone the repository will contain a single local branch, which
50eca761 129will be the current branch as well, as indicated by the asterisk.
39219fd3
YO
130
131 % git branch
132 * blead
133
f755e97d 134Using the -a switch to C<branch> will also show the remote tracking
6acba58e 135branches in the repository:
39219fd3 136
d9847473 137 % git branch -a
09081495 138 * blead
d7dd28b6
LB
139 origin/HEAD
140 origin/blead
141 ...
142
6acba58e
LB
143The branches that begin with "origin" correspond to the "git remote"
144that you cloned from (which is named "origin"). Each branch on the
145remote will be exactly tracked by theses branches. You should NEVER do
146work on these remote tracking branches. You only ever do work in a
147local branch. Local branches can be configured to automerge (on pull)
148from a designated remote tracking branch. This is the case with the
149default branch C<blead> which will be configured to merge from the
150remote tracking branch C<origin/blead>.
39219fd3 151
d7dd28b6
LB
152You can see recent commits:
153
c2cf2042 154 % git log
d7dd28b6 155
6acba58e
LB
156And pull new changes from the repository, and update your local
157repository (must be clean first)
d7dd28b6
LB
158
159 % git pull
09081495 160
6acba58e
LB
161Assuming we are on the branch C<blead> immediately after a pull, this
162command would be more or less equivalent to:
39219fd3
YO
163
164 % git fetch
165 % git merge origin/blead
166
6acba58e
LB
167In fact if you want to update your local repository without touching
168your working directory you do:
39219fd3
YO
169
170 % git fetch
171
6acba58e
LB
172And if you want to update your remote-tracking branches for all defined
173remotes simultaneously you can do
39219fd3
YO
174
175 % git remote update
176
6acba58e
LB
177Neither of these last two commands will update your working directory,
178however both will update the remote-tracking branches in your
179repository.
39219fd3 180
6051489b
NC
181To make a local branch of a remote branch:
182
183 % git checkout -b maint-5.10 origin/maint-5.10
184
09081495
LB
185To switch back to blead:
186
187 % git checkout blead
c2cf2042 188
ba336be1 189=head2 Finding out your status
39219fd3
YO
190
191The most common git command you will use will probably be
192
193 % git status
194
6acba58e
LB
195This command will produce as output a description of the current state
196of the repository, including modified files and unignored untracked
197files, and in addition it will show things like what files have been
198staged for the next commit, and usually some useful information about
199how to change things. For instance the following:
39219fd3
YO
200
201 $ git status
202 # On branch blead
203 # Your branch is ahead of 'origin/blead' by 1 commit.
204 #
205 # Changes to be committed:
206 # (use "git reset HEAD <file>..." to unstage)
207 #
208 # modified: pod/perlrepository.pod
209 #
210 # Changed but not updated:
211 # (use "git add <file>..." to update what will be committed)
212 #
213 # modified: pod/perlrepository.pod
214 #
215 # Untracked files:
216 # (use "git add <file>..." to include in what will be committed)
217 #
218 # deliberate.untracked
219
6acba58e
LB
220This shows that there were changes to this document staged for commit,
221and that there were further changes in the working directory not yet
222staged. It also shows that there was an untracked file in the working
223directory, and as you can see shows how to change all of this. It also
0549aefb
LB
224shows that there is one commit on the working branch C<blead> which has
225not been pushed to the C<origin> remote yet. B<NOTE>: that this output
226is also what you see as a template if you do not provide a message to
227C<git commit>.
7f6effc7 228
bdaf0bc6
JV
229Assuming that you'd like to commit all the changes you've just made as a
230a single atomic unit, run this command:
231
232 % git commit -a
233
234(That C<-a> tells git to add every file you've changed to this commit.
ea9c0d74
JV
235New files aren't automatically added to your commit when you use C<commit
236-a> If you want to add files or to commit some, but not all of your
237changes, have a look at the documentation for C<git add>.)
bdaf0bc6 238
e9360695 239Git will start up your favorite text editor, so that you can craft a
bdaf0bc6
JV
240commit message for your change. See L</Commit message> below for more
241information about what makes a good commit message.
242
243Once you've finished writing your commit message and exited your editor,
244git will write your change to disk and tell you something like this:
7f6effc7 245
7f6effc7
YO
246 Created commit daf8e63: explain git status and stuff about remotes
247 1 files changed, 83 insertions(+), 3 deletions(-)
248
bdaf0bc6
JV
249
250If you re-run C<git status>, you should see something like this:
7f6effc7
YO
251
252 % git status
253 # On branch blead
254 # Your branch is ahead of 'origin/blead' by 2 commits.
255 #
256 # Untracked files:
257 # (use "git add <file>..." to include in what will be committed)
258 #
259 # deliberate.untracked
260 nothing added to commit but untracked files present (use "git add" to track)
261
39219fd3 262
6acba58e
LB
263When in doubt, before you do anything else, check your status and read
264it carefully, many questions are answered directly by the git status
265output.
39219fd3 266
ba336be1 267=head1 Submitting a patch
c2cf2042
LB
268
269If you have a patch in mind for Perl, you should first get a copy of
270the repository:
271
272 % git clone git://perl5.git.perl.org/perl.git perl-git
273
274Then change into the directory:
275
276 % cd perl-git
277
6acba58e
LB
278Alternatively, if you already have a Perl repository, you should ensure
279that you're on the I<blead> branch, and your repository is up to date:
12322d22
A
280
281 % git checkout blead
282 % git pull
283
6a7cbfe8
LB
284It's preferable to patch against the latest blead version, since this
285is where new development occurs for all changes other than critical bug
286fixes. Critical bug fix patches should be made against the relevant
7f4ffa9d
RS
287maint branches, or should be submitted with a note indicating all the
288branches where the fix should be applied.
a44f43ac 289
6acba58e
LB
290Now that we have everything up to date, we need to create a temporary
291new branch for these changes and switch into it:
b1fccde5 292
a9b05323 293 % git checkout -b orange
23f8d33e 294
a9b05323
YO
295which is the short form of
296
b1fccde5
LB
297 % git branch orange
298 % git checkout orange
299
0c24b290
AB
300Creating a topic branch makes it easier for the maintainers to rebase
301or merge back into the master blead for a more linear history. If you
302don't work on a topic branch the maintainer has to manually cherry
303pick your changes onto blead before they can be applied.
304
305That'll get you scolded on perl5-porters, so don't do that. Be
306Awesome.
307
c2cf2042
LB
308Then make your changes. For example, if Leon Brocard changes his name
309to Orange Brocard, we should change his name in the AUTHORS file:
310
311 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
312
313You can see what files are changed:
314
315 % git status
f755e97d 316 # On branch orange
c2cf2042
LB
317 # Changes to be committed:
318 # (use "git reset HEAD <file>..." to unstage)
319 #
2699d634 320 # modified: AUTHORS
c2cf2042
LB
321 #
322
c2cf2042
LB
323And you can see the changes:
324
325 % git diff
326 diff --git a/AUTHORS b/AUTHORS
327 index 293dd70..722c93e 100644
328 --- a/AUTHORS
329 +++ b/AUTHORS
7df2e4bc 330 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
c2cf2042
LB
331 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
332 Leif Huhn <leif@hale.dkstat.com>
333 Len Johnson <lenjay@ibm.net>
334 -Leon Brocard <acme@astray.com>
335 +Orange Brocard <acme@astray.com>
336 Les Peters <lpeters@aol.net>
337 Lesley Binks <lesley.binks@gmail.com>
338 Lincoln D. Stein <lstein@cshl.org>
339
340Now commit your change locally:
341
dc3c3040 342 % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
c2cf2042
LB
343 Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
344 1 files changed, 1 insertions(+), 1 deletions(-)
345
dc3c3040
GA
346You can examine your last commit with:
347
348 % git show HEAD
349
350and if you are not happy with either the description or the patch
c26da522 351itself you can fix it up by editing the files once more and then issue:
dc3c3040
GA
352
353 % git commit -a --amend
354
c2cf2042
LB
355Now you should create a patch file for all your local changes:
356
f15b1f22 357 % git format-patch -M origin..
c2cf2042
LB
358 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
359
dce3ee48
AB
360You should now send an email to to
361L<perlbug@perl.org|mailto:perlbug@perl.org> with a description of your
362changes, and include this patch file as an attachment. In addition to
363being tracked by RT, mail to perlbug will automatically be forwarded
364to perl5-porters. You should only send patches to
365L<perl5-porters@perl.org|mailto:perl5-porters@perl.org> directly if the
366patch is not ready to be applied, but intended for discussion.
64a8e22b
AB
367
368See the next section for how to configure and use git to send these
369emails for you.
c2cf2042 370
b1fccde5
LB
371If you want to delete your temporary branch, you may do so with:
372
373 % git checkout blead
374 % git branch -d orange
375 error: The branch 'orange' is not an ancestor of your current HEAD.
376 If you are sure you want to delete it, run 'git branch -D orange'.
377 % git branch -D orange
378 Deleted branch orange.
7df2e4bc 379
2d5f1d01
DG
380=head2 Using git to send patch emails
381
64a8e22b
AB
382In your ~/git/perl repository, set the destination email to perl's bug
383tracker:
384
385 $ git config sendemail.to perlbug@perl.org
386
387Or maybe perl5-porters (discussed above):
2d5f1d01
DG
388
389 $ git config sendemail.to perl5-porters@perl.org
390
391Then you can use git directly to send your patch emails:
392
393 $ git send-email 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
394
333f8875
VP
395You may need to set some configuration variables for your particular
396email service provider. For example, to set your global git config to
397send email via a gmail account:
2d5f1d01
DG
398
399 $ git config --global sendemail.smtpserver smtp.gmail.com
400 $ git config --global sendemail.smtpssl 1
401 $ git config --global sendemail.smtpuser YOURUSERNAME@gmail.com
402
333f8875
VP
403With this configuration, you will be prompted for your gmail password
404when you run 'git send-email'. You can also configure
405C<sendemail.smtppass> with your password if you don't care about having
406your password in the .gitconfig file.
2d5f1d01 407
a44f43ac
RGS
408=head2 A note on derived files
409
410Be aware that many files in the distribution are derivative--avoid
0549aefb
LB
411patching them, because git won't see the changes to them, and the build
412process will overwrite them. Patch the originals instead. Most
413utilities (like perldoc) are in this category, i.e. patch
0be741b5 414F<utils/perldoc.PL> rather than F<utils/perldoc>. Similarly, don't create
0549aefb
LB
415patches for files under $src_root/ext from their copies found in
416$install_root/lib. If you are unsure about the proper location of a
417file that may have gotten copied while building the source
418distribution, consult the C<MANIFEST>.
a44f43ac 419
ac1cbfb0
JC
420As a special case, several files are regenerated by 'make regen' if
421your patch alters C<embed.fnc>. These are needed for compilation, but
422are included in the distribution so that you can build perl without
423needing another perl to generate the files. You must test with these
424regenerated files, but it is preferred that you instead note that
425'make regen is needed' in both the email and the commit message, and
426submit your patch without them. If you're submitting a series of
427patches, it might be best to submit the regenerated changes
428immediately after the source-changes that caused them, so as to have
429as little effect as possible on the bisectability of your patchset.
430
6e2cec71 431=for XXX
a44f43ac 432
6e2cec71 433What should we recommend about binary files now? Do we need anything?
a44f43ac
RGS
434
435=head2 Getting your patch accepted
436
bdaf0bc6 437If you are submitting a code patch there are several things that
a44f43ac
RGS
438you need to do.
439
440=over 4
441
bdaf0bc6
JV
442=item Commit message
443
444As you craft each patch you intend to submit to the Perl core, it's
445important to write a good commit message.
446
1a5f98ea
AB
447The first line of the commit message should be a short description and
448should skip the full stop. It should be no longer than the subject
449line of an E-Mail, 50 characters being a good rule of thumb.
450
451A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ..) will
452only display the first line (cut off at 50 characters) when presenting
453commit summaries.
454
455The commit message should include description of the problem that the
456patch corrects or new functionality that the patch adds.
bdaf0bc6 457
bdaf0bc6
JV
458As a general rule of thumb, your commit message should let a programmer
459with a reasonable familiarity with the Perl core quickly understand what
460you were trying to do, how you were trying to do it and why the change
461matters to Perl.
462
463=over 4
464
465=item What
466
ac1cbfb0
JC
467Your commit message should describe what part of the Perl core you're
468changing and what you expect your patch to do.
bdaf0bc6
JV
469
470=item Why
471
472Perhaps most importantly, your commit message should describe why the
473change you are making is important. When someone looks at your change
474in six months or six years, your intent should be clear. If you're
475deprecating a feature with the intent of later simplifying another bit
476of code, say so. If you're fixing a performance problem or adding a new
477feature to support some other bit of the core, mention that.
478
479=item How
480
481While it's not necessary for documentation changes, new tests or
482trivial patches, it's often worth explaining how your change works.
483Even if it's clear to you today, it may not be clear to a porter next
484month or next year.
485
486=back
487
ea9c0d74
JV
488A commit message isn't intended to take the place of comments in your
489code. Commit messages should describe the change you made, while code
80a0006a
JV
490comments should describe the current state of the code. If you've just
491implemented a new feature, complete with doc, tests and well-commented
492code, a brief commit message will often suffice. If, however, you've
493just changed a single character deep in the parser or lexer, you might
ea9c0d74
JV
494need to write a small novel to ensure that future readers understand
495what you did and why you did it.
496
a44f43ac
RGS
497=item Comments, Comments, Comments
498
0549aefb
LB
499Be sure to adequately comment your code. While commenting every line
500is unnecessary, anything that takes advantage of side effects of
a44f43ac 501operators, that creates changes that will be felt outside of the
0549aefb
LB
502function being patched, or that others may find confusing should be
503documented. If you are going to err, it is better to err on the side
504of adding too many comments than too few.
a44f43ac
RGS
505
506=item Style
507
0549aefb
LB
508In general, please follow the particular style of the code you are
509patching.
a44f43ac 510
0549aefb
LB
511In particular, follow these general guidelines for patching Perl
512sources:
a44f43ac
RGS
513
514 8-wide tabs (no exceptions!)
515 4-wide indents for code, 2-wide indents for nested CPP #defines
516 try hard not to exceed 79-columns
517 ANSI C prototypes
518 uncuddled elses and "K&R" style for indenting control constructs
519 no C++ style (//) comments
520 mark places that need to be revisited with XXX (and revisit often!)
521 opening brace lines up with "if" when conditional spans multiple
522 lines; should be at end-of-line otherwise
523 in function definitions, name starts in column 0 (return value is on
524 previous line)
525 single space after keywords that are followed by parens, no space
526 between function name and following paren
527 avoid assignments in conditionals, but if they're unavoidable, use
528 extra paren, e.g. "if (a && (b = c)) ..."
529 "return foo;" rather than "return(foo);"
530 "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
531
532=item Testsuite
533
bdaf0bc6
JV
534If your patch changes code (rather than just changing documentation) you
535should also include one or more test cases which illustrate the bug you're
536fixing or validate the new functionality you're adding. In general,
537you should update an existing test file rather than create a new one.
538
0549aefb
LB
539Your testsuite additions should generally follow these guidelines
540(courtesy of Gurusamy Sarathy <gsar@activestate.com>):
a44f43ac
RGS
541
542 Know what you're testing. Read the docs, and the source.
543 Tend to fail, not succeed.
544 Interpret results strictly.
545 Use unrelated features (this will flush out bizarre interactions).
546 Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
547 Avoid using hardcoded test numbers whenever possible (the
548 EXPECTED/GOT found in t/op/tie.t is much more maintainable,
549 and gives better failure reports).
550 Give meaningful error messages when a test fails.
551 Avoid using qx// and system() unless you are testing for them. If you
552 do use them, make sure that you cover _all_ perl platforms.
553 Unlink any temporary files you create.
554 Promote unforeseen warnings to errors with $SIG{__WARN__}.
555 Be sure to use the libraries and modules shipped with the version
556 being tested, not those that were already installed.
557 Add comments to the code explaining what you are testing for.
558 Make updating the '1..42' string unnecessary. Or make sure that
559 you update it.
560 Test _all_ behaviors of a given operator, library, or function:
561 - All optional arguments
562 - Return values in various contexts (boolean, scalar, list, lvalue)
563 - Use both global and lexical variables
564 - Don't forget the exceptional, pathological cases.
565
566=back
567
ba336be1 568=head1 Accepting a patch
7df2e4bc
LB
569
570If you have received a patch file generated using the above section,
571you should try out the patch.
572
573First we need to create a temporary new branch for these changes and
574switch into it:
575
a9b05323 576 % git checkout -b experimental
7df2e4bc 577
6acba58e
LB
578Patches that were formatted by C<git format-patch> are applied with
579C<git am>:
7df2e4bc 580
2af192ee 581 % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
7df2e4bc
LB
582 Applying Rename Leon Brocard to Orange Brocard
583
6acba58e
LB
584If just a raw diff is provided, it is also possible use this two-step
585process:
09645c26
VP
586
587 % git apply bugfix.diff
dc3c3040 588 % git commit -a -m "Some fixing" --author="That Guy <that.guy@internets.com>"
09645c26 589
7df2e4bc
LB
590Now we can inspect the change:
591
dc3c3040 592 % git show HEAD
7df2e4bc
LB
593 commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
594 Author: Leon Brocard <acme@astray.com>
595 Date: Fri Dec 19 17:02:59 2008 +0000
596
597 Rename Leon Brocard to Orange Brocard
7df2e4bc 598
7df2e4bc
LB
599 diff --git a/AUTHORS b/AUTHORS
600 index 293dd70..722c93e 100644
601 --- a/AUTHORS
602 +++ b/AUTHORS
603 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
604 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
605 Leif Huhn <leif@hale.dkstat.com>
606 Len Johnson <lenjay@ibm.net>
607 -Leon Brocard <acme@astray.com>
608 +Orange Brocard <acme@astray.com>
609 Les Peters <lpeters@aol.net>
610 Lesley Binks <lesley.binks@gmail.com>
611 Lincoln D. Stein <lstein@cshl.org>
612
613If you are a committer to Perl and you think the patch is good, you can
75fb7651 614then merge it into blead then push it out to the main repository:
7df2e4bc
LB
615
616 % git checkout blead
d9847473 617 % git merge experimental
75fb7651 618 % git push
7df2e4bc
LB
619
620If you want to delete your temporary branch, you may do so with:
621
622 % git checkout blead
623 % git branch -d experimental
624 error: The branch 'experimental' is not an ancestor of your current HEAD.
625 If you are sure you want to delete it, run 'git branch -D experimental'.
626 % git branch -D experimental
627 Deleted branch experimental.
b0d36535 628
ba336be1 629=head1 Cleaning a working directory
b0d36535 630
6acba58e 631The command C<git clean> can with varying arguments be used as a
dc3c3040 632replacement for C<make clean>.
b0d36535
YO
633
634To reset your working directory to a pristine condition you can do:
635
e0b2b458 636 % git clean -dxf
b0d36535
YO
637
638However, be aware this will delete ALL untracked content. You can use
639
e0b2b458 640 % git clean -Xf
b0d36535 641
6acba58e
LB
642to remove all ignored untracked files, such as build and test
643byproduct, but leave any manually created files alone.
b0d36535 644
0549aefb 645If you only want to cancel some uncommitted edits, you can use C<git
c26da522
LB
646checkout> and give it a list of files to be reverted, or C<git checkout
647-f> to revert them all.
f755e97d
RGS
648
649If you want to cancel one or several commits, you can use C<git reset>.
650
ba336be1 651=head1 Bisecting
d82a90c1 652
6acba58e
LB
653C<git> provides a built-in way to determine, with a binary search in
654the history, which commit should be blamed for introducing a given bug.
d82a90c1 655
6acba58e 656Suppose that we have a script F<~/testcase.pl> that exits with C<0>
bdaf0bc6 657when some behaviour is correct, and with C<1> when it's faulty. You need
6acba58e
LB
658an helper script that automates building C<perl> and running the
659testcase:
d82a90c1
VP
660
661 % cat ~/run
662 #!/bin/sh
663 git clean -dxf
a4583001
AB
664
665 # If you get './makedepend: 1: Syntax error: Unterminated quoted
666 # string' when bisecting versions of perl older than 5.9.5 this hack
667 # will work around the bug in makedepend.SH which was fixed in
cfe91bfa 668 # version 96a8704c. Make sure to comment out `git checkout makedepend.SH'
a4583001
AB
669 # below too.
670 git show blead:makedepend.SH > makedepend.SH
671
d82a90c1 672 # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
1d5fe431
MB
673 # if Encode is not needed for the test, you can speed up the bisect by
674 # excluding it from the runs with -Dnoextensions=Encode
c0d1ef72
MB
675 sh Configure -des -Dusedevel -Doptimize="-g"
676 test -f config.sh || exit 125
677 # Correct makefile for newer GNU gcc
678 perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile
679 # if you just need miniperl, replace test_prep with miniperl
d7923bfe 680 make test_prep
68814ba4 681 [ -x ./perl ] || exit 125
d82a90c1 682 ./perl -Ilib ~/testcase.pl
c0d1ef72 683 ret=$?
7930c68b 684 [ $ret -gt 127 ] && ret=127
cfe91bfa 685 # git checkout makedepend.SH
c0d1ef72
MB
686 git clean -dxf
687 exit $ret
d82a90c1 688
6acba58e
LB
689This script may return C<125> to indicate that the corresponding commit
690should be skipped. Otherwise, it returns the status of
691F<~/testcase.pl>.
d82a90c1 692
bdaf0bc6 693You first enter in bisect mode with:
d82a90c1
VP
694
695 % git bisect start
696
6acba58e
LB
697For example, if the bug is present on C<HEAD> but wasn't in 5.10.0,
698C<git> will learn about this when you enter:
d82a90c1
VP
699
700 % git bisect bad
701 % git bisect good perl-5.10.0
702 Bisecting: 853 revisions left to test after this
703
6acba58e 704This results in checking out the median commit between C<HEAD> and
bdaf0bc6 705C<perl-5.10.0>. You can then run the bisecting process with:
d82a90c1
VP
706
707 % git bisect run ~/run
708
709When the first bad commit is isolated, C<git bisect> will tell you so:
710
711 ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
712 commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
713 Author: Dave Mitchell <davem@fdisolutions.com>
714 Date: Sat Feb 9 14:56:23 2008 +0000
715
9469eb4a 716 [perl #49472] Attributes + Unknown Error
d82a90c1
VP
717 ...
718
719 bisect run success
720
6acba58e
LB
721You can peek into the bisecting process with C<git bisect log> and
722C<git bisect visualize>. C<git bisect reset> will get you out of bisect
723mode.
d82a90c1 724
6acba58e
LB
725Please note that the first C<good> state must be an ancestor of the
726first C<bad> state. If you want to search for the commit that I<solved>
727some bug, you have to negate your test case (i.e. exit with C<1> if OK
728and C<0> if not) and still mark the lower bound as C<good> and the
729upper as C<bad>. The "first bad commit" has then to be understood as
730the "first commit where the bug is solved".
d82a90c1 731
6acba58e
LB
732C<git help bisect> has much more information on how you can tweak your
733binary searches.
9d68b7ed 734
ba336be1 735=head1 Submitting a patch via GitHub
03050721
LB
736
737GitHub is a website that makes it easy to fork and publish projects
738with Git. First you should set up a GitHub account and log in.
739
740Perl's git repository is mirrored on GitHub at this page:
741
45b194c5 742 http://github.com/mirrors/perl/tree/blead
03050721
LB
743
744Visit the page and click the "fork" button. This clones the Perl git
745repository for you and provides you with "Your Clone URL" from which
746you should clone:
747
748 % git clone git@github.com:USERNAME/perl.git perl-github
749
bdaf0bc6 750The same patch as above, using github might look like this:
03050721
LB
751
752 % cd perl-github
edb9e29e 753 % git remote add upstream git://perl5.git.perl.org/perl.git
03050721
LB
754 % git pull upstream blead
755 % git checkout -b orange
756 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
dc3c3040 757 % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
03050721
LB
758 % git push origin orange
759
760The orange branch has been pushed to GitHub, so you should now send an
705c800c 761email (see L</Submitting a patch>) with a description of your changes
64a8e22b 762and the following information:
03050721
LB
763
764 http://github.com/USERNAME/perl/tree/orange
fb60e745 765 git://github.com/USERNAME/perl.git branch orange
03050721 766
ba336be1 767=head1 Merging from a branch via GitHub
c26da522
LB
768
769If someone has provided a branch via GitHub and you are a committer,
5c9c28c6 770you should use the following in your perl-ssh directory:
c26da522 771
e98adcab
AB
772 % git remote add avar git://github.com/avar/perl.git
773 % git fetch avar
c26da522
LB
774
775Now you can see the differences between the branch and blead:
776
e98adcab 777 % git diff avar/orange
c26da522
LB
778
779And you can see the commits:
780
e98adcab 781 % git log avar/orange
c26da522
LB
782
783If you approve of a specific commit, you can cherry pick it:
784
e98adcab 785 % git cherry-pick 0c24b290ae02b2ab3304f51d5e11e85eb3659eae
2bab0636
LB
786
787Or you could just merge the whole branch if you like it all:
788
e98adcab 789 % git merge avar/orange
c26da522
LB
790
791And then push back to the repository:
792
793 % git push
794
ce2a8773 795
ba336be1 796=head1 Topic branches and rewriting history
ce2a8773
JV
797
798Individual committers should create topic branches under
333f8875
VP
799B<yourname>/B<some_descriptive_name>. Other committers should check
800with a topic branch's creator before making any change to it.
ce2a8773 801
b16add97
AP
802The simplest way to create a remote topic branch that works on all
803versions of git is to push the current head as a new branch on the
804remote, then check it out locally:
805
806 $ branch="$yourname/$some_descriptive_name"
807 $ git push origin HEAD:$branch
808 $ git checkout -b $branch origin/$branch
809
810Users of git 1.7 or newer can do it in a more obvious manner:
811
812 $ branch="$yourname/$some_descriptive_name"
813 $ git checkout -b $branch
814 $ git push origin -u $branch
33e5002f 815
ce2a8773
JV
816If you are not the creator of B<yourname>/B<some_descriptive_name>, you
817might sometimes find that the original author has edited the branch's
818history. There are lots of good reasons for this. Sometimes, an author
333f8875
VP
819might simply be rebasing the branch onto a newer source point.
820Sometimes, an author might have found an error in an early commit which
821they wanted to fix before merging the branch to blead.
ce2a8773 822
333f8875
VP
823Currently the master repository is configured to forbid
824non-fast-forward merges. This means that the branches within can not
825be rebased and pushed as a single step.
ce2a8773 826
333f8875
VP
827The only way you will ever be allowed to rebase or modify the history
828of a pushed branch is to delete it and push it as a new branch under
829the same name. Please think carefully about doing this. It may be
830better to sequentially rename your branches so that it is easier for
831others working with you to cherry-pick their local changes onto the new
832version. (XXX: needs explanation).
ce2a8773
JV
833
834If you want to rebase a personal topic branch, you will have to delete
2699d634
YO
835your existing topic branch and push as a new version of it. You can do
836this via the following formula (see the explanation about C<refspec>'s
837in the git push documentation for details) after you have rebased your
838branch:
839
840 # first rebase
841 $ git checkout $user/$topic
842 $ git fetch
843 $ git rebase origin/blead
844
845 # then "delete-and-push"
846 $ git push origin :$user/$topic
847 $ git push origin $user/$topic
848
849B<NOTE:> it is forbidden at the repository level to delete any of the
333f8875
VP
850"primary" branches. That is any branch matching
851C<m!^(blead|maint|perl)!>. Any attempt to do so will result in git
852producing an error like this:
2699d634
YO
853
854 $ git push origin :blead
855 *** It is forbidden to delete blead/maint branches in this repository
856 error: hooks/update exited with error code 1
857 error: hook declined to update refs/heads/blead
333f8875 858 To ssh://perl5.git.perl.org/perl
2699d634 859 ! [remote rejected] blead (hook declined)
333f8875 860 error: failed to push some refs to 'ssh://perl5.git.perl.org/perl'
2699d634 861
333f8875
VP
862As a matter of policy we do B<not> edit the history of the blead and
863maint-* branches. If a typo (or worse) sneaks into a commit to blead or
864maint-*, we'll fix it in another commit. The only types of updates
865allowed on these branches are "fast-forward's", where all history is
866preserved.
2699d634 867
333f8875
VP
868Annotated tags in the canonical perl.git repository will never be
869deleted or modified. Think long and hard about whether you want to push
870a local tag to perl.git before doing so. (Pushing unannotated tags is
2699d634 871not allowed.)
ce2a8773 872
ba336be1 873=head1 Committing to maintenance versions
9d68b7ed 874
041325d6
AB
875Maintenance versions should only be altered to add critical bug
876fixes, see L<perlpolicy>.
7f4ffa9d 877
9d68b7ed
LB
878To commit to a maintenance version of perl, you need to create a local
879tracking branch:
880
881 % git checkout --track -b maint-5.005 origin/maint-5.005
882
0549aefb
LB
883This creates a local branch named C<maint-5.005>, which tracks the
884remote branch C<origin/maint-5.005>. Then you can pull, commit, merge
885and push as before.
b0d36535 886
f755e97d 887You can also cherry-pick commits from blead and another branch, by
0549aefb
LB
888using the C<git cherry-pick> command. It is recommended to use the
889B<-x> option to C<git cherry-pick> in order to record the SHA1 of the
890original commit in the new commit message.
f755e97d 891
ba336be1 892=head1 Grafts
e8589bfa
AV
893
894The perl history contains one mistake which was not caught in the
ac036724 895conversion: a merge was recorded in the history between blead and
333f8875
VP
896maint-5.10 where no merge actually occurred. Due to the nature of git,
897this is now impossible to fix in the public repository. You can remove
898this mis-merge locally by adding the following line to your
e8589bfa
AV
899C<.git/info/grafts> file:
900
901 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930
902
903It is particularly important to have this graft line if any bisecting
904is done in the area of the "merge" in question.
905
041325d6 906=head1 SEE ALSO
bdaf0bc6 907
041325d6 908=over
bdaf0bc6 909
705c800c 910=item *
041325d6 911
705c800c
RGS
912The git documentation, accessible via the C<git help> command
913
914=item *
915
916L<perlpolicy> - Perl core development policy
041325d6
AB
917
918=back
f755e97d 919
041325d6 920=cut