This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Run podtidy on pod/perlrepository.pod and document how to do so
[perl5.git] / pod / perlrepository.pod
CommitLineData
0549aefb
LB
1=for comment
2Consistent formatting of this file is achieved with:
3 perl ./Porting/podtidy pod/perlrepository.pod
4
d7dd28b6
LB
5=head1 NAME
6
7perlrepository - Using the Perl source repository
8
9=head1 SYNOPSIS
10
11All of Perl's source code is kept centrally in a Git repository. The
6acba58e
LB
12repository contains many Perl revisions from Perl 1 onwards and all the
13revisions from Perforce, the version control system we were using
d7dd28b6
LB
14previously. This repository is accessible in different ways.
15
16The full repository takes up about 80MB of disk space. A check out of
d9847473
RGS
17the blead branch (that is, the master branch, which contains bleadperl,
18the development version of perl 5) takes up about 160MB of disk space
19(including the repository). A build of bleadperl takes up about 200MB
20(including the repository and the check out).
d7dd28b6
LB
21
22=head1 GETTING ACCESS TO THE REPOSITORY
23
24=head2 READ ACCESS VIA THE WEB
25
26You may access this over the web. This allows you to browse the tree,
27see recent commits, search for particular commits and more. You may
28access it at:
29
30 http://perl5.git.perl.org/perl.git
31
32=head2 READ ACCESS VIA GIT
33
34You will need a copy of Git for your computer. You can fetch a copy of
35the repository using the Git protocol (which uses port 9418):
36
3b8a5fb0 37 git clone git://perl5.git.perl.org/perl.git perl-git
d7dd28b6 38
f755e97d 39This clones the repository and makes a local copy in the F<perl-git>
d7dd28b6
LB
40directory.
41
42If your local network does not allow you to use port 9418, then you can
572f57ba 43fetch a copy of the repository over HTTP (this is slower):
d7dd28b6 44
3b8a5fb0 45 git clone http://perl5.git.perl.org/perl.git perl-http
d7dd28b6 46
f755e97d 47This clones the repository and makes a local copy in the F<perl-http>
d7dd28b6
LB
48directory.
49
50=head2 WRITE ACCESS TO THE REPOSITORY
51
6acba58e
LB
52If you are a committer, then you can fetch a copy of the repository
53that you can push back on with:
d7dd28b6 54
3b8a5fb0 55 git clone ssh://perl5.git.perl.org/gitroot/perl.git perl-ssh
d7dd28b6 56
8f718e95 57This clones the repository and makes a local copy in the F<perl-ssh>
d7dd28b6
LB
58directory.
59
1a0f15d5 60If you clone using git, which is faster than ssh, then you will need to
6acba58e
LB
61modify your config in order to enable pushing. Edit F<.git/config>
62where you will see something like:
1a0f15d5
YO
63
64 [remote "origin"]
65 url = git://perl5.git.perl.org/perl.git
66
67change that to something like this:
68
69 [remote "origin"]
70 url = ssh://perl5.git.perl.org/gitroot/perl.git
71
6acba58e
LB
72NOTE: there are symlinks set up so that the /gitroot is actually
73optional.
d7dd28b6 74
184487f0
NC
75You can also set up your user name and e-mail address. For example
76
77 % git config user.name "Leon Brocard"
78 % git config user.email acme@astray.com
79
6acba58e
LB
80It is also possible to keep C<origin> as a git remote, and add a new
81remote for ssh access:
f6c12373
VP
82
83 % git remote add camel user@camel:/gitroot/perl.git
84
6acba58e 85This allows you to update your local repository by pulling from
f755e97d 86C<origin>, which is faster and doesn't require you to authenticate, and
6acba58e 87to push your changes back with the C<camel> remote:
f6c12373
VP
88
89 % git fetch camel
90 % git push camel
91
6acba58e
LB
92The C<fetch> command just updates the C<camel> refs, as the objects
93themselves should have been fetched when pulling from C<origin>.
f6c12373 94
d7dd28b6
LB
95=head1 OVERVIEW OF THE REPOSITORY
96
6acba58e
LB
97Once you have changed into the repository directory, you can inspect
98it.
d7dd28b6 99
39219fd3 100After a clone the repository will contain a single local branch, which
50eca761 101will be the current branch as well, as indicated by the asterisk.
39219fd3
YO
102
103 % git branch
104 * blead
105
f755e97d 106Using the -a switch to C<branch> will also show the remote tracking
6acba58e 107branches in the repository:
39219fd3 108
d9847473 109 % git branch -a
09081495 110 * blead
d7dd28b6
LB
111 origin/HEAD
112 origin/blead
113 ...
114
6acba58e
LB
115The branches that begin with "origin" correspond to the "git remote"
116that you cloned from (which is named "origin"). Each branch on the
117remote will be exactly tracked by theses branches. You should NEVER do
118work on these remote tracking branches. You only ever do work in a
119local branch. Local branches can be configured to automerge (on pull)
120from a designated remote tracking branch. This is the case with the
121default branch C<blead> which will be configured to merge from the
122remote tracking branch C<origin/blead>.
39219fd3 123
d7dd28b6
LB
124You can see recent commits:
125
c2cf2042 126 % git log
d7dd28b6 127
6acba58e
LB
128And pull new changes from the repository, and update your local
129repository (must be clean first)
d7dd28b6
LB
130
131 % git pull
09081495 132
6acba58e
LB
133Assuming we are on the branch C<blead> immediately after a pull, this
134command would be more or less equivalent to:
39219fd3
YO
135
136 % git fetch
137 % git merge origin/blead
138
6acba58e
LB
139In fact if you want to update your local repository without touching
140your working directory you do:
39219fd3
YO
141
142 % git fetch
143
6acba58e
LB
144And if you want to update your remote-tracking branches for all defined
145remotes simultaneously you can do
39219fd3
YO
146
147 % git remote update
148
6acba58e
LB
149Neither of these last two commands will update your working directory,
150however both will update the remote-tracking branches in your
151repository.
39219fd3 152
09081495
LB
153To switch to another branch:
154
155 % git checkout origin/maint-5.8-dor
156
6051489b
NC
157To make a local branch of a remote branch:
158
159 % git checkout -b maint-5.10 origin/maint-5.10
160
09081495
LB
161To switch back to blead:
162
163 % git checkout blead
c2cf2042 164
39219fd3
YO
165=head2 FINDING OUT YOUR STATUS
166
167The most common git command you will use will probably be
168
169 % git status
170
6acba58e
LB
171This command will produce as output a description of the current state
172of the repository, including modified files and unignored untracked
173files, and in addition it will show things like what files have been
174staged for the next commit, and usually some useful information about
175how to change things. For instance the following:
39219fd3
YO
176
177 $ git status
178 # On branch blead
179 # Your branch is ahead of 'origin/blead' by 1 commit.
180 #
181 # Changes to be committed:
182 # (use "git reset HEAD <file>..." to unstage)
183 #
184 # modified: pod/perlrepository.pod
185 #
186 # Changed but not updated:
187 # (use "git add <file>..." to update what will be committed)
188 #
189 # modified: pod/perlrepository.pod
190 #
191 # Untracked files:
192 # (use "git add <file>..." to include in what will be committed)
193 #
194 # deliberate.untracked
195
6acba58e
LB
196This shows that there were changes to this document staged for commit,
197and that there were further changes in the working directory not yet
198staged. It also shows that there was an untracked file in the working
199directory, and as you can see shows how to change all of this. It also
0549aefb
LB
200shows that there is one commit on the working branch C<blead> which has
201not been pushed to the C<origin> remote yet. B<NOTE>: that this output
202is also what you see as a template if you do not provide a message to
203C<git commit>.
7f6effc7
YO
204
205Assuming we commit all the mentioned changes above:
206
207 % git commit -a -m'explain git status and stuff about remotes'
208 Created commit daf8e63: explain git status and stuff about remotes
209 1 files changed, 83 insertions(+), 3 deletions(-)
210
211We can re-run git status and see something like this:
212
213 % git status
214 # On branch blead
215 # Your branch is ahead of 'origin/blead' by 2 commits.
216 #
217 # Untracked files:
218 # (use "git add <file>..." to include in what will be committed)
219 #
220 # deliberate.untracked
221 nothing added to commit but untracked files present (use "git add" to track)
222
39219fd3 223
6acba58e
LB
224When in doubt, before you do anything else, check your status and read
225it carefully, many questions are answered directly by the git status
226output.
39219fd3 227
c2cf2042
LB
228=head1 SUBMITTING A PATCH
229
230If you have a patch in mind for Perl, you should first get a copy of
231the repository:
232
233 % git clone git://perl5.git.perl.org/perl.git perl-git
234
235Then change into the directory:
236
237 % cd perl-git
238
6acba58e
LB
239Alternatively, if you already have a Perl repository, you should ensure
240that you're on the I<blead> branch, and your repository is up to date:
12322d22
A
241
242 % git checkout blead
243 % git pull
244
0549aefb
LB
245(It's preferable to patch against the latest blead version, since
246patches are usually integrated from blead to the maintenance branches.
247This does not apply, obviously, in the rare case where your patch is
248specific to a maintaince release.)
a44f43ac 249
6acba58e
LB
250Now that we have everything up to date, we need to create a temporary
251new branch for these changes and switch into it:
b1fccde5 252
a9b05323 253 % git checkout -b orange
23f8d33e 254
a9b05323
YO
255which is the short form of
256
b1fccde5
LB
257 % git branch orange
258 % git checkout orange
259
c2cf2042
LB
260Then make your changes. For example, if Leon Brocard changes his name
261to Orange Brocard, we should change his name in the AUTHORS file:
262
263 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
264
265You can see what files are changed:
266
267 % git status
f755e97d 268 # On branch orange
c2cf2042
LB
269 # Changes to be committed:
270 # (use "git reset HEAD <file>..." to unstage)
271 #
272 # modified: AUTHORS
273 #
274
c2cf2042
LB
275And you can see the changes:
276
277 % git diff
278 diff --git a/AUTHORS b/AUTHORS
279 index 293dd70..722c93e 100644
280 --- a/AUTHORS
281 +++ b/AUTHORS
7df2e4bc 282 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
c2cf2042
LB
283 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
284 Leif Huhn <leif@hale.dkstat.com>
285 Len Johnson <lenjay@ibm.net>
286 -Leon Brocard <acme@astray.com>
287 +Orange Brocard <acme@astray.com>
288 Les Peters <lpeters@aol.net>
289 Lesley Binks <lesley.binks@gmail.com>
290 Lincoln D. Stein <lstein@cshl.org>
291
292Now commit your change locally:
293
294 % git add AUTHORS
295 % git commit -m 'Rename Leon Brocard to Orange Brocard'
296 Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
297 1 files changed, 1 insertions(+), 1 deletions(-)
298
299Now you should create a patch file for all your local changes:
300
2af192ee 301 % git format-patch origin
c2cf2042
LB
302 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
303
304You should now send an email to perl5-porters@perl.org with a
305description of your changes, and attach this patch file as an
306attachment.
307
b1fccde5
LB
308If you want to delete your temporary branch, you may do so with:
309
310 % git checkout blead
311 % git branch -d orange
312 error: The branch 'orange' is not an ancestor of your current HEAD.
313 If you are sure you want to delete it, run 'git branch -D orange'.
314 % git branch -D orange
315 Deleted branch orange.
7df2e4bc 316
a44f43ac
RGS
317=head2 A note on derived files
318
319Be aware that many files in the distribution are derivative--avoid
0549aefb
LB
320patching them, because git won't see the changes to them, and the build
321process will overwrite them. Patch the originals instead. Most
322utilities (like perldoc) are in this category, i.e. patch
323utils/perldoc.PL rather than utils/perldoc. Similarly, don't create
324patches for files under $src_root/ext from their copies found in
325$install_root/lib. If you are unsure about the proper location of a
326file that may have gotten copied while building the source
327distribution, consult the C<MANIFEST>.
a44f43ac
RGS
328
329=head2 A note on binary files
330
0549aefb
LB
331Since the patch(1) utility cannot deal with binary files, it's
332important that you either avoid the use of binary files in your patch,
333generate the files dynamically, or that you encode any binary files
334using the F<uupacktool.pl> utility.
a44f43ac
RGS
335
336Assuming you needed to include a gzip-encoded file for a module's test
337suite, you might do this as follows using the F<uupacktool.pl> utility:
338
339 $ perl uupacktool.pl -v -p -D lib/Some/Module/t/src/t.gz
340 Writing lib/Some/Module/t/src/t.gz into lib/Some/Module/t/src/t.gz.packed
341
342This will replace the C<t.gz> file with an encoded counterpart. During
0549aefb
LB
343C<make test>, before any tests are run, perl's Makefile will restore
344all the C<.packed> files mentioned in the MANIFEST to their original
345name. This means that the test suite does not need to be aware of this
346packing scheme and will not need to be altered.
a44f43ac
RGS
347
348=head2 Getting your patch accepted
349
0549aefb
LB
350The first thing you should include with your patch is a description of
351the problem that the patch corrects. If it is a code patch (rather
352than a documentation patch) you should also include a small test case
353that illustrates the bug (a patch to an existing test file is
354preferred).
a44f43ac
RGS
355
356If you are submitting a code patch there are several other things that
357you need to do.
358
359=over 4
360
361=item Comments, Comments, Comments
362
0549aefb
LB
363Be sure to adequately comment your code. While commenting every line
364is unnecessary, anything that takes advantage of side effects of
a44f43ac 365operators, that creates changes that will be felt outside of the
0549aefb
LB
366function being patched, or that others may find confusing should be
367documented. If you are going to err, it is better to err on the side
368of adding too many comments than too few.
a44f43ac
RGS
369
370=item Style
371
0549aefb
LB
372In general, please follow the particular style of the code you are
373patching.
a44f43ac 374
0549aefb
LB
375In particular, follow these general guidelines for patching Perl
376sources:
a44f43ac
RGS
377
378 8-wide tabs (no exceptions!)
379 4-wide indents for code, 2-wide indents for nested CPP #defines
380 try hard not to exceed 79-columns
381 ANSI C prototypes
382 uncuddled elses and "K&R" style for indenting control constructs
383 no C++ style (//) comments
384 mark places that need to be revisited with XXX (and revisit often!)
385 opening brace lines up with "if" when conditional spans multiple
386 lines; should be at end-of-line otherwise
387 in function definitions, name starts in column 0 (return value is on
388 previous line)
389 single space after keywords that are followed by parens, no space
390 between function name and following paren
391 avoid assignments in conditionals, but if they're unavoidable, use
392 extra paren, e.g. "if (a && (b = c)) ..."
393 "return foo;" rather than "return(foo);"
394 "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
395
396=item Testsuite
397
0549aefb
LB
398When submitting a patch you should make every effort to also include an
399addition to perl's regression tests to properly exercise your patch.
400Your testsuite additions should generally follow these guidelines
401(courtesy of Gurusamy Sarathy <gsar@activestate.com>):
a44f43ac
RGS
402
403 Know what you're testing. Read the docs, and the source.
404 Tend to fail, not succeed.
405 Interpret results strictly.
406 Use unrelated features (this will flush out bizarre interactions).
407 Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
408 Avoid using hardcoded test numbers whenever possible (the
409 EXPECTED/GOT found in t/op/tie.t is much more maintainable,
410 and gives better failure reports).
411 Give meaningful error messages when a test fails.
412 Avoid using qx// and system() unless you are testing for them. If you
413 do use them, make sure that you cover _all_ perl platforms.
414 Unlink any temporary files you create.
415 Promote unforeseen warnings to errors with $SIG{__WARN__}.
416 Be sure to use the libraries and modules shipped with the version
417 being tested, not those that were already installed.
418 Add comments to the code explaining what you are testing for.
419 Make updating the '1..42' string unnecessary. Or make sure that
420 you update it.
421 Test _all_ behaviors of a given operator, library, or function:
422 - All optional arguments
423 - Return values in various contexts (boolean, scalar, list, lvalue)
424 - Use both global and lexical variables
425 - Don't forget the exceptional, pathological cases.
426
427=back
428
7df2e4bc
LB
429=head1 ACCEPTING A PATCH
430
431If you have received a patch file generated using the above section,
432you should try out the patch.
433
434First we need to create a temporary new branch for these changes and
435switch into it:
436
a9b05323 437 % git checkout -b experimental
7df2e4bc 438
6acba58e
LB
439Patches that were formatted by C<git format-patch> are applied with
440C<git am>:
7df2e4bc 441
2af192ee 442 % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
7df2e4bc
LB
443 Applying Rename Leon Brocard to Orange Brocard
444
6acba58e
LB
445If just a raw diff is provided, it is also possible use this two-step
446process:
09645c26
VP
447
448 % git apply bugfix.diff
449 % git commit -am "Some fixing" --author="That Guy <that.guy@internets.com>"
450
7df2e4bc
LB
451Now we can inspect the change:
452
453 % git log
454 commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
455 Author: Leon Brocard <acme@astray.com>
456 Date: Fri Dec 19 17:02:59 2008 +0000
457
458 Rename Leon Brocard to Orange Brocard
459 ...
460
461 % git diff blead
462 diff --git a/AUTHORS b/AUTHORS
463 index 293dd70..722c93e 100644
464 --- a/AUTHORS
465 +++ b/AUTHORS
466 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
467 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
468 Leif Huhn <leif@hale.dkstat.com>
469 Len Johnson <lenjay@ibm.net>
470 -Leon Brocard <acme@astray.com>
471 +Orange Brocard <acme@astray.com>
472 Les Peters <lpeters@aol.net>
473 Lesley Binks <lesley.binks@gmail.com>
474 Lincoln D. Stein <lstein@cshl.org>
475
476If you are a committer to Perl and you think the patch is good, you can
75fb7651 477then merge it into blead then push it out to the main repository:
7df2e4bc
LB
478
479 % git checkout blead
d9847473 480 % git merge experimental
75fb7651 481 % git push
7df2e4bc
LB
482
483If you want to delete your temporary branch, you may do so with:
484
485 % git checkout blead
486 % git branch -d experimental
487 error: The branch 'experimental' is not an ancestor of your current HEAD.
488 If you are sure you want to delete it, run 'git branch -D experimental'.
489 % git branch -D experimental
490 Deleted branch experimental.
b0d36535
YO
491
492=head1 CLEANING A WORKING DIRECTORY
493
6acba58e
LB
494The command C<git clean> can with varying arguments be used as a
495replacement for make-clean.
b0d36535
YO
496
497To reset your working directory to a pristine condition you can do:
498
499 git clean -dxf
500
501However, be aware this will delete ALL untracked content. You can use
502
503 git clean -Xf
504
6acba58e
LB
505to remove all ignored untracked files, such as build and test
506byproduct, but leave any manually created files alone.
b0d36535 507
0549aefb
LB
508If you only want to cancel some uncommitted edits, you can use C<git
509checkout> and give it a list of files to be reverted.
f755e97d
RGS
510
511If you want to cancel one or several commits, you can use C<git reset>.
512
d82a90c1
VP
513=head1 BISECTING
514
6acba58e
LB
515C<git> provides a built-in way to determine, with a binary search in
516the history, which commit should be blamed for introducing a given bug.
d82a90c1 517
6acba58e
LB
518Suppose that we have a script F<~/testcase.pl> that exits with C<0>
519when some behaviour is correct, and with C<1> when it's faulty. We need
520an helper script that automates building C<perl> and running the
521testcase:
d82a90c1
VP
522
523 % cat ~/run
524 #!/bin/sh
525 git clean -dxf
526 # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
527 sh Configure -des -Dusedevel -Doptimize="-g" || exit 125
528 make || exit 125
529 ./perl -Ilib ~/testcase.pl
530
6acba58e
LB
531This script may return C<125> to indicate that the corresponding commit
532should be skipped. Otherwise, it returns the status of
533F<~/testcase.pl>.
d82a90c1
VP
534
535We first enter in bisect mode with:
536
537 % git bisect start
538
6acba58e
LB
539For example, if the bug is present on C<HEAD> but wasn't in 5.10.0,
540C<git> will learn about this when you enter:
d82a90c1
VP
541
542 % git bisect bad
543 % git bisect good perl-5.10.0
544 Bisecting: 853 revisions left to test after this
545
6acba58e
LB
546This results in checking out the median commit between C<HEAD> and
547C<perl-5.10.0>. We can then run the bisecting process with:
d82a90c1
VP
548
549 % git bisect run ~/run
550
551When the first bad commit is isolated, C<git bisect> will tell you so:
552
553 ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
554 commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
555 Author: Dave Mitchell <davem@fdisolutions.com>
556 Date: Sat Feb 9 14:56:23 2008 +0000
557
9469eb4a 558 [perl #49472] Attributes + Unknown Error
d82a90c1
VP
559 ...
560
561 bisect run success
562
6acba58e
LB
563You can peek into the bisecting process with C<git bisect log> and
564C<git bisect visualize>. C<git bisect reset> will get you out of bisect
565mode.
d82a90c1 566
6acba58e
LB
567Please note that the first C<good> state must be an ancestor of the
568first C<bad> state. If you want to search for the commit that I<solved>
569some bug, you have to negate your test case (i.e. exit with C<1> if OK
570and C<0> if not) and still mark the lower bound as C<good> and the
571upper as C<bad>. The "first bad commit" has then to be understood as
572the "first commit where the bug is solved".
d82a90c1 573
6acba58e
LB
574C<git help bisect> has much more information on how you can tweak your
575binary searches.
9d68b7ed 576
9469eb4a 577=head1 COMMITTING TO MAINTENANCE VERSIONS
9d68b7ed
LB
578
579To commit to a maintenance version of perl, you need to create a local
580tracking branch:
581
582 % git checkout --track -b maint-5.005 origin/maint-5.005
583
0549aefb
LB
584This creates a local branch named C<maint-5.005>, which tracks the
585remote branch C<origin/maint-5.005>. Then you can pull, commit, merge
586and push as before.
b0d36535 587
f755e97d 588You can also cherry-pick commits from blead and another branch, by
0549aefb
LB
589using the C<git cherry-pick> command. It is recommended to use the
590B<-x> option to C<git cherry-pick> in order to record the SHA1 of the
591original commit in the new commit message.
f755e97d
RGS
592
593=head1 SEE ALSO
594
595The git documentation, accessible via C<git help command>.
0549aefb 596