1PERLREPOSITORY(1) Perl Programmers Reference Guide PERLREPOSITORY(1)
2
6 perlrepository - Using the Perl source repository
7
9 All of Perl's source code is kept centrally in a Git repository at
10 perl5.git.perl.org. The repository contains many Perl revisions from
11 Perl 1 onwards and all the revisions from Perforce, the version control
12 system we were using previously. This repository is accessible in
13 different ways.
14 The full repository takes up about 80MB of disk space. A check out of
16 the blead branch (that is, the main development branch, which contains
17 bleadperl, the development version of perl 5) takes up about 160MB of
18 disk space (including the repository). A build of bleadperl takes up
19 about 200MB (including the repository and the check out).
20
22 READ ACCESS VIA THE WEB
23 You may access the repository over the web. This allows you to browse
24 the tree, see recent commits, subscribe to RSS feeds for the changes,
25 search for particular commits and more. You may access it at:
26 http://perl5.git.perl.org/perl.git
28 A mirror of the repository is found at:
30 http://github.com/github/perl
32 READ ACCESS VIA GIT
34 You will need a copy of Git for your computer. You can fetch a copy of
35 the repository using the Git protocol (which uses port 9418):
36 git clone git://perl5.git.perl.org/perl.git perl-git
38 This clones the repository and makes a local copy in the perl-git
40 directory.
41 If your local network does not allow you to use port 9418, then you can
43 fetch a copy of the repository over HTTP (this is slower):
44 git clone http://perl5.git.perl.org/perl.git perl-http
46 This clones the repository and makes a local copy in the perl-http
48 directory.
49 WRITE ACCESS TO THE REPOSITORY
51 If you are a committer, then you can fetch a copy of the repository
52 that you can push back on with:
53 git clone ssh://perl5.git.perl.org/gitroot/perl.git perl-ssh
55 This clones the repository and makes a local copy in the perl-ssh
57 directory.
58 If you cloned using the git protocol, which is faster than ssh, then
60 you will need to modify your config in order to enable pushing. Edit
61 .git/config where you will see something like:
62 [remote "origin"]
64 url = git://perl5.git.perl.org/perl.git
65 change that to something like this:
67 [remote "origin"]
69 url = ssh://perl5.git.perl.org/gitroot/perl.git
70 NOTE: there are symlinks set up so that the /gitroot is optional and
72 since SSH is the default protocol you can actually shorten the "url" to
73 "perl5.git.perl.org:/perl.git".
74 You can also set up your user name and e-mail address. For example
76 % git config user.name "Leon Brocard"
78 % git config user.email acme@astray.com
79 It is also possible to keep "origin" as a git remote, and add a new
81 remote for ssh access:
82 % git remote add camel perl5.git.perl.org:/perl.git
84 This allows you to update your local repository by pulling from
86 "origin", which is faster and doesn't require you to authenticate, and
87 to push your changes back with the "camel" remote:
88 % git fetch camel
90 % git push camel
91 The "fetch" command just updates the "camel" refs, as the objects
93 themselves should have been fetched when pulling from "origin".
94 The committers have access to 2 servers that serve perl5.git.perl.org.
96 One is camel.booking.com, which is the 'master' repository. The
97 perl5.git.perl.org IP address also lives on this machine. The second
98 one is dromedary.booking.com, which can be used for general testing and
99 development. Dromedary syncs the git tree from camel every few minutes,
100 you should not push there. Both machines also have a full CPAN mirror.
101 To share files with the general public, dromedary serves your
102 ~/public_html/ as http://users.perl5.git.perl.org/~yourlogin/
103
105 Once you have changed into the repository directory, you can inspect
106 it.
107 After a clone the repository will contain a single local branch, which
109 will be the current branch as well, as indicated by the asterisk.
110 % git branch
112 * blead
113 Using the -a switch to "branch" will also show the remote tracking
115 branches in the repository:
116 % git branch -a
118 * blead
119 origin/HEAD
120 origin/blead
121 ...
122 The branches that begin with "origin" correspond to the "git remote"
124 that you cloned from (which is named "origin"). Each branch on the
125 remote will be exactly tracked by theses branches. You should NEVER do
126 work on these remote tracking branches. You only ever do work in a
127 local branch. Local branches can be configured to automerge (on pull)
128 from a designated remote tracking branch. This is the case with the
129 default branch "blead" which will be configured to merge from the
130 remote tracking branch "origin/blead".
131 You can see recent commits:
133 % git log
135 And pull new changes from the repository, and update your local
137 repository (must be clean first)
138 % git pull
140 Assuming we are on the branch "blead" immediately after a pull, this
142 command would be more or less equivalent to:
143 % git fetch
145 % git merge origin/blead
146 In fact if you want to update your local repository without touching
148 your working directory you do:
149 % git fetch
151 And if you want to update your remote-tracking branches for all defined
153 remotes simultaneously you can do
154 % git remote update
156 Neither of these last two commands will update your working directory,
158 however both will update the remote-tracking branches in your
159 repository.
160 To switch to another branch:
162 % git checkout origin/maint-5.8-dor
164 To make a local branch of a remote branch:
166 % git checkout -b maint-5.10 origin/maint-5.10
168 To switch back to blead:
170 % git checkout blead
172 FINDING OUT YOUR STATUS
174 The most common git command you will use will probably be
175 % git status
177 This command will produce as output a description of the current state
179 of the repository, including modified files and unignored untracked
180 files, and in addition it will show things like what files have been
181 staged for the next commit, and usually some useful information about
182 how to change things. For instance the following:
183 $ git status
185 # On branch blead
186 # Your branch is ahead of 'origin/blead' by 1 commit.
187 #
188 # Changes to be committed:
189 # (use "git reset HEAD <file>..." to unstage)
190 #
191 # modified: pod/perlrepository.pod
192 #
193 # Changed but not updated:
194 # (use "git add <file>..." to update what will be committed)
195 #
196 # modified: pod/perlrepository.pod
197 #
198 # Untracked files:
199 # (use "git add <file>..." to include in what will be committed)
200 #
201 # deliberate.untracked
202 This shows that there were changes to this document staged for commit,
204 and that there were further changes in the working directory not yet
205 staged. It also shows that there was an untracked file in the working
206 directory, and as you can see shows how to change all of this. It also
207 shows that there is one commit on the working branch "blead" which has
208 not been pushed to the "origin" remote yet. NOTE: that this output is
209 also what you see as a template if you do not provide a message to "git
210 commit".
211 Assuming we commit all the mentioned changes above:
213 % git commit -a -m'explain git status and stuff about remotes'
215 Created commit daf8e63: explain git status and stuff about remotes
216 1 files changed, 83 insertions(+), 3 deletions(-)
217 We can re-run git status and see something like this:
219 % git status
221 # On branch blead
222 # Your branch is ahead of 'origin/blead' by 2 commits.
223 #
224 # Untracked files:
225 # (use "git add <file>..." to include in what will be committed)
226 #
227 # deliberate.untracked
228 nothing added to commit but untracked files present (use "git add" to track)
229 When in doubt, before you do anything else, check your status and read
231 it carefully, many questions are answered directly by the git status
232 output.
233
235 If you have a patch in mind for Perl, you should first get a copy of
236 the repository:
237 % git clone git://perl5.git.perl.org/perl.git perl-git
239 Then change into the directory:
241 % cd perl-git
243 Alternatively, if you already have a Perl repository, you should ensure
245 that you're on the blead branch, and your repository is up to date:
246 % git checkout blead
248 % git pull
249 It's preferable to patch against the latest blead version, since this
251 is where new development occurs for all changes other than critical bug
252 fixes. Critical bug fix patches should be made against the relevant
253 maint branches, or should be submitted with a note indicating all the
254 branches where the fix should be applied.
255 Now that we have everything up to date, we need to create a temporary
257 new branch for these changes and switch into it:
258 % git checkout -b orange
260 which is the short form of
262 % git branch orange
264 % git checkout orange
265 Then make your changes. For example, if Leon Brocard changes his name
267 to Orange Brocard, we should change his name in the AUTHORS file:
268 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
270 You can see what files are changed:
272 % git status
274 # On branch orange
275 # Changes to be committed:
276 # (use "git reset HEAD <file>..." to unstage)
277 #
278 # modified: AUTHORS
279 #
280 And you can see the changes:
282 % git diff
284 diff --git a/AUTHORS b/AUTHORS
285 index 293dd70..722c93e 100644
286 --- a/AUTHORS
287 +++ b/AUTHORS
288 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
289 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
290 Leif Huhn <leif@hale.dkstat.com>
291 Len Johnson <lenjay@ibm.net>
292 -Leon Brocard <acme@astray.com>
293 +Orange Brocard <acme@astray.com>
294 Les Peters <lpeters@aol.net>
295 Lesley Binks <lesley.binks@gmail.com>
296 Lincoln D. Stein <lstein@cshl.org>
297 Now commit your change locally:
299 % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
301 Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
302 1 files changed, 1 insertions(+), 1 deletions(-)
303 You can examine your last commit with:
305 % git show HEAD
307 and if you are not happy with either the description or the patch
309 itself you can fix it up by editing the files once more and then issue:
310 % git commit -a --amend
312 Now you should create a patch file for all your local changes:
314 % git format-patch origin
316 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
317 You should now send an email to perl5-porters@perl.org with a
319 description of your changes, and include this patch file as an
320 attachment.
321 If you want to delete your temporary branch, you may do so with:
323 % git checkout blead
325 % git branch -d orange
326 error: The branch 'orange' is not an ancestor of your current HEAD.
327 If you are sure you want to delete it, run 'git branch -D orange'.
328 % git branch -D orange
329 Deleted branch orange.
330 A note on derived files
332 Be aware that many files in the distribution are derivative--avoid
333 patching them, because git won't see the changes to them, and the build
334 process will overwrite them. Patch the originals instead. Most
335 utilities (like perldoc) are in this category, i.e. patch
336 utils/perldoc.PL rather than utils/perldoc. Similarly, don't create
337 patches for files under $src_root/ext from their copies found in
338 $install_root/lib. If you are unsure about the proper location of a
339 file that may have gotten copied while building the source
340 distribution, consult the "MANIFEST".
341 A note on binary files
343 Since the patch(1) utility cannot deal with binary files, it's
344 important that you either avoid the use of binary files in your patch,
345 generate the files dynamically, or that you encode any binary files
346 using the uupacktool.pl utility.
347 Assuming you needed to include a gzip-encoded file for a module's test
349 suite, you might do this as follows using the uupacktool.pl utility:
350 $ perl uupacktool.pl -v -p -D lib/Some/Module/t/src/t.gz
352 Writing lib/Some/Module/t/src/t.gz into lib/Some/Module/t/src/t.gz.packed
353 This will replace the "t.gz" file with an encoded counterpart. During
355 "make test", before any tests are run, perl's Makefile will restore all
356 the ".packed" files mentioned in the MANIFEST to their original name.
357 This means that the test suite does not need to be aware of this
358 packing scheme and will not need to be altered.
359 Getting your patch accepted
361 The first thing you should include with your patch is a description of
362 the problem that the patch corrects. If it is a code patch (rather
363 than a documentation patch) you should also include a small test case
364 that illustrates the bug (a patch to an existing test file is
365 preferred).
366 If you are submitting a code patch there are several other things that
368 you need to do.
369 Comments, Comments, Comments
371 Be sure to adequately comment your code. While commenting every
372 line is unnecessary, anything that takes advantage of side effects
373 of operators, that creates changes that will be felt outside of the
374 function being patched, or that others may find confusing should be
375 documented. If you are going to err, it is better to err on the
376 side of adding too many comments than too few.
377 Style
379 In general, please follow the particular style of the code you are
380 patching.
381 In particular, follow these general guidelines for patching Perl
383 sources:
384 8-wide tabs (no exceptions!)
386 4-wide indents for code, 2-wide indents for nested CPP #defines
387 try hard not to exceed 79-columns
388 ANSI C prototypes
389 uncuddled elses and "K&R" style for indenting control constructs
390 no C++ style (//) comments
391 mark places that need to be revisited with XXX (and revisit often!)
392 opening brace lines up with "if" when conditional spans multiple
393 lines; should be at end-of-line otherwise
394 in function definitions, name starts in column 0 (return value is on
395 previous line)
396 single space after keywords that are followed by parens, no space
397 between function name and following paren
398 avoid assignments in conditionals, but if they're unavoidable, use
399 extra paren, e.g. "if (a && (b = c)) ..."
400 "return foo;" rather than "return(foo);"
401 "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
402 Testsuite
404 When submitting a patch you should make every effort to also
405 include an addition to perl's regression tests to properly exercise
406 your patch. Your testsuite additions should generally follow these
407 guidelines (courtesy of Gurusamy Sarathy <gsar@activestate.com>):
408 Know what you're testing. Read the docs, and the source.
410 Tend to fail, not succeed.
411 Interpret results strictly.
412 Use unrelated features (this will flush out bizarre interactions).
413 Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
414 Avoid using hardcoded test numbers whenever possible (the
415 EXPECTED/GOT found in t/op/tie.t is much more maintainable,
416 and gives better failure reports).
417 Give meaningful error messages when a test fails.
418 Avoid using qx// and system() unless you are testing for them. If you
419 do use them, make sure that you cover _all_ perl platforms.
420 Unlink any temporary files you create.
421 Promote unforeseen warnings to errors with $SIG{__WARN__}.
422 Be sure to use the libraries and modules shipped with the version
423 being tested, not those that were already installed.
424 Add comments to the code explaining what you are testing for.
425 Make updating the '1..42' string unnecessary. Or make sure that
426 you update it.
427 Test _all_ behaviors of a given operator, library, or function:
428 - All optional arguments
429 - Return values in various contexts (boolean, scalar, list, lvalue)
430 - Use both global and lexical variables
431 - Don't forget the exceptional, pathological cases.
432
434 If you have received a patch file generated using the above section,
435 you should try out the patch.
436 First we need to create a temporary new branch for these changes and
438 switch into it:
439 % git checkout -b experimental
441 Patches that were formatted by "git format-patch" are applied with "git
443 am":
444 % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
446 Applying Rename Leon Brocard to Orange Brocard
447 If just a raw diff is provided, it is also possible use this two-step
449 process:
450 % git apply bugfix.diff
452 % git commit -a -m "Some fixing" --author="That Guy <that.guy@internets.com>"
453 Now we can inspect the change:
455 % git show HEAD
457 commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
458 Author: Leon Brocard <acme@astray.com>
459 Date: Fri Dec 19 17:02:59 2008 +0000
460 Rename Leon Brocard to Orange Brocard
462 diff --git a/AUTHORS b/AUTHORS
464 index 293dd70..722c93e 100644
465 --- a/AUTHORS
466 +++ b/AUTHORS
467 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
468 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
469 Leif Huhn <leif@hale.dkstat.com>
470 Len Johnson <lenjay@ibm.net>
471 -Leon Brocard <acme@astray.com>
472 +Orange Brocard <acme@astray.com>
473 Les Peters <lpeters@aol.net>
474 Lesley Binks <lesley.binks@gmail.com>
475 Lincoln D. Stein <lstein@cshl.org>
476 If you are a committer to Perl and you think the patch is good, you can
478 then merge it into blead then push it out to the main repository:
479 % git checkout blead
481 % git merge experimental
482 % git push
483 If you want to delete your temporary branch, you may do so with:
485 % git checkout blead
487 % git branch -d experimental
488 error: The branch 'experimental' is not an ancestor of your current HEAD.
489 If you are sure you want to delete it, run 'git branch -D experimental'.
490 % git branch -D experimental
491 Deleted branch experimental.
492
494 The command "git clean" can with varying arguments be used as a
495 replacement for "make clean".
496 To reset your working directory to a pristine condition you can do:
498 git clean -dxf
500 However, be aware this will delete ALL untracked content. You can use
502 git clean -Xf
504 to remove all ignored untracked files, such as build and test
506 byproduct, but leave any manually created files alone.
507 If you only want to cancel some uncommitted edits, you can use "git
509 checkout" and give it a list of files to be reverted, or "git checkout
510 -f" to revert them all.
511 If you want to cancel one or several commits, you can use "git reset".
513
515 "git" provides a built-in way to determine, with a binary search in the
516 history, which commit should be blamed for introducing a given bug.
517 Suppose that we have a script ~/testcase.pl that exits with 0 when some
519 behaviour is correct, and with 1 when it's faulty. We need an helper
520 script that automates building "perl" and running the testcase:
521 % cat ~/run
523 #!/bin/sh
524 git clean -dxf
525 # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
526 sh Configure -des -Dusedevel -Doptimize="-g"
527 test -f config.sh || exit 125
528 # Correct makefile for newer GNU gcc
529 perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile
530 # if you just need miniperl, replace test_prep with miniperl
531 make -j4 test_prep
532 -x ./perl || exit 125
533 ./perl -Ilib ~/testcase.pl
534 ret=$?
535 git clean -dxf
536 exit $ret
537 This script may return 125 to indicate that the corresponding commit
539 should be skipped. Otherwise, it returns the status of ~/testcase.pl.
540 We first enter in bisect mode with:
542 % git bisect start
544 For example, if the bug is present on "HEAD" but wasn't in 5.10.0,
546 "git" will learn about this when you enter:
547 % git bisect bad
549 % git bisect good perl-5.10.0
550 Bisecting: 853 revisions left to test after this
551 This results in checking out the median commit between "HEAD" and
553 "perl-5.10.0". We can then run the bisecting process with:
554 % git bisect run ~/run
556 When the first bad commit is isolated, "git bisect" will tell you so:
558 ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
560 commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
561 Author: Dave Mitchell <davem@fdisolutions.com>
562 Date: Sat Feb 9 14:56:23 2008 +0000
563 [perl #49472] Attributes + Unknown Error
565 ...
566 bisect run success
568 You can peek into the bisecting process with "git bisect log" and "git
570 bisect visualize". "git bisect reset" will get you out of bisect mode.
571 Please note that the first "good" state must be an ancestor of the
573 first "bad" state. If you want to search for the commit that solved
574 some bug, you have to negate your test case (i.e. exit with 1 if OK and
575 0 if not) and still mark the lower bound as "good" and the upper as
576 "bad". The "first bad commit" has then to be understood as the "first
577 commit where the bug is solved".
578 "git help bisect" has much more information on how you can tweak your
580 binary searches.
581
583 GitHub is a website that makes it easy to fork and publish projects
584 with Git. First you should set up a GitHub account and log in.
585 Perl's git repository is mirrored on GitHub at this page:
587 http://github.com/github/perl/tree/blead
589 Visit the page and click the "fork" button. This clones the Perl git
591 repository for you and provides you with "Your Clone URL" from which
592 you should clone:
593 % git clone git@github.com:USERNAME/perl.git perl-github
595 We shall make the same patch as above, creating a new branch:
597 % cd perl-github
599 % git remote add upstream git://github.com/github/perl.git
600 % git pull upstream blead
601 % git checkout -b orange
602 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
603 % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
604 % git push origin orange
605 The orange branch has been pushed to GitHub, so you should now send an
607 email to perl5-porters@perl.org with a description of your changes and
608 the following information:
609 http://github.com/USERNAME/perl/tree/orange
611 git@github.com:USERNAME/perl.git branch orange
612
614 If someone has provided a branch via GitHub and you are a committer,
615 you should use the following in your perl-ssh directory:
616 % git remote add dandv git://github.com/dandv/perl.git
618 % git fetch
619 Now you can see the differences between the branch and blead:
621 % git diff dandv/blead
623 And you can see the commits:
625 % git log dandv/blead
627 If you approve of a specific commit, you can cherry pick it:
629 % git cherry-pick 3adac458cb1c1d41af47fc66e67b49c8dec2323f
631 Or you could just merge the whole branch if you like it all:
633 % git merge dandv/blead
635 And then push back to the repository:
637 % git push
639
641 Maintenance versions should only be altered to add critical bug fixes.
642 To commit to a maintenance version of perl, you need to create a local
644 tracking branch:
645 % git checkout --track -b maint-5.005 origin/maint-5.005
647 This creates a local branch named "maint-5.005", which tracks the
649 remote branch "origin/maint-5.005". Then you can pull, commit, merge
650 and push as before.
651 You can also cherry-pick commits from blead and another branch, by
653 using the "git cherry-pick" command. It is recommended to use the -x
654 option to "git cherry-pick" in order to record the SHA1 of the original
655 commit in the new commit message.
656
658 The git documentation, accessible via "git help command".
659perl v5.10.1 2009-08-03 PERLREPOSITORY(1)