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