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