This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[perl #108754] perlgit.pod: Stress rebase more
[perl5.git] / pod / perlgit.pod
CommitLineData
49781f4a
AB
1=encoding utf8
2
0549aefb
LB
3=for comment
4Consistent formatting of this file is achieved with:
04c692a8 5 perl ./Porting/podtidy pod/perlgit.pod
0549aefb 6
d7dd28b6
LB
7=head1 NAME
8
04c692a8 9perlgit - Detailed information about git and the Perl repository
d7dd28b6 10
04c692a8 11=head1 DESCRIPTION
d7dd28b6 12
04c692a8
DR
13This document provides details on using git to develop Perl. If you are
14just interested in working on a quick patch, see L<perlhack> first.
15This document is intended for people who are regular contributors to
16Perl, including those with write access to the git repository.
184487f0 17
04c692a8 18=head1 CLONING THE REPOSITORY
f6c12373 19
04c692a8
DR
20All of Perl's source code is kept centrally in a Git repository at
21I<perl5.git.perl.org>.
f6c12373 22
04c692a8 23You can make a read-only clone of the repository by running:
f6c12373 24
04c692a8 25 % git clone git://perl5.git.perl.org/perl.git perl
f6c12373 26
04c692a8 27This uses the git protocol (port 9418).
f6c12373 28
04c692a8
DR
29If you cannot use the git protocol for firewall reasons, you can also
30clone via http, though this is much slower:
3482f01a 31
04c692a8 32 % git clone http://perl5.git.perl.org/perl.git perl
b47aa495 33
04c692a8 34=head1 WORKING WITH THE REPOSITORY
d7dd28b6 35
6acba58e 36Once you have changed into the repository directory, you can inspect
04c692a8
DR
37it. After a clone the repository will contain a single local branch,
38which will be the current branch as well, as indicated by the asterisk.
39219fd3
YO
39
40 % git branch
41 * blead
42
f755e97d 43Using the -a switch to C<branch> will also show the remote tracking
6acba58e 44branches in the repository:
39219fd3 45
d9847473 46 % git branch -a
09081495 47 * blead
d7dd28b6
LB
48 origin/HEAD
49 origin/blead
50 ...
51
6acba58e
LB
52The branches that begin with "origin" correspond to the "git remote"
53that you cloned from (which is named "origin"). Each branch on the
c9d1da35 54remote will be exactly tracked by these branches. You should NEVER do
6acba58e
LB
55work on these remote tracking branches. You only ever do work in a
56local branch. Local branches can be configured to automerge (on pull)
57from a designated remote tracking branch. This is the case with the
58default branch C<blead> which will be configured to merge from the
59remote tracking branch C<origin/blead>.
39219fd3 60
d7dd28b6
LB
61You can see recent commits:
62
c2cf2042 63 % git log
d7dd28b6 64
6acba58e
LB
65And pull new changes from the repository, and update your local
66repository (must be clean first)
d7dd28b6
LB
67
68 % git pull
09081495 69
6acba58e
LB
70Assuming we are on the branch C<blead> immediately after a pull, this
71command would be more or less equivalent to:
39219fd3
YO
72
73 % git fetch
74 % git merge origin/blead
75
6acba58e
LB
76In fact if you want to update your local repository without touching
77your working directory you do:
39219fd3
YO
78
79 % git fetch
80
6acba58e
LB
81And if you want to update your remote-tracking branches for all defined
82remotes simultaneously you can do
39219fd3
YO
83
84 % git remote update
85
6acba58e
LB
86Neither of these last two commands will update your working directory,
87however both will update the remote-tracking branches in your
88repository.
39219fd3 89
6051489b
NC
90To make a local branch of a remote branch:
91
92 % git checkout -b maint-5.10 origin/maint-5.10
93
09081495
LB
94To switch back to blead:
95
96 % git checkout blead
c2cf2042 97
ba336be1 98=head2 Finding out your status
39219fd3
YO
99
100The most common git command you will use will probably be
101
102 % git status
103
6acba58e
LB
104This command will produce as output a description of the current state
105of the repository, including modified files and unignored untracked
106files, and in addition it will show things like what files have been
107staged for the next commit, and usually some useful information about
108how to change things. For instance the following:
39219fd3
YO
109
110 $ git status
111 # On branch blead
112 # Your branch is ahead of 'origin/blead' by 1 commit.
113 #
114 # Changes to be committed:
115 # (use "git reset HEAD <file>..." to unstage)
116 #
04c692a8 117 # modified: pod/perlgit.pod
39219fd3
YO
118 #
119 # Changed but not updated:
120 # (use "git add <file>..." to update what will be committed)
121 #
04c692a8 122 # modified: pod/perlgit.pod
39219fd3
YO
123 #
124 # Untracked files:
125 # (use "git add <file>..." to include in what will be committed)
126 #
127 # deliberate.untracked
128
6acba58e
LB
129This shows that there were changes to this document staged for commit,
130and that there were further changes in the working directory not yet
131staged. It also shows that there was an untracked file in the working
132directory, and as you can see shows how to change all of this. It also
0549aefb
LB
133shows that there is one commit on the working branch C<blead> which has
134not been pushed to the C<origin> remote yet. B<NOTE>: that this output
135is also what you see as a template if you do not provide a message to
136C<git commit>.
7f6effc7 137
04c692a8 138=head2 Patch workflow
7f6effc7 139
04c692a8
DR
140First, please read L<perlhack> for details on hacking the Perl core.
141That document covers many details on how to create a good patch.
7f6effc7 142
04c692a8
DR
143If you already have a Perl repository, you should ensure that you're on
144the I<blead> branch, and your repository is up to date:
12322d22
A
145
146 % git checkout blead
147 % git pull
148
6a7cbfe8
LB
149It's preferable to patch against the latest blead version, since this
150is where new development occurs for all changes other than critical bug
04c692a8 151fixes. Critical bug fix patches should be made against the relevant
7f4ffa9d
RS
152maint branches, or should be submitted with a note indicating all the
153branches where the fix should be applied.
a44f43ac 154
6acba58e
LB
155Now that we have everything up to date, we need to create a temporary
156new branch for these changes and switch into it:
b1fccde5 157
a9b05323 158 % git checkout -b orange
23f8d33e 159
a9b05323
YO
160which is the short form of
161
b1fccde5
LB
162 % git branch orange
163 % git checkout orange
164
0c24b290
AB
165Creating a topic branch makes it easier for the maintainers to rebase
166or merge back into the master blead for a more linear history. If you
77db6475
LB
167don't work on a topic branch the maintainer has to manually cherry pick
168your changes onto blead before they can be applied.
0c24b290 169
77db6475 170That'll get you scolded on perl5-porters, so don't do that. Be Awesome.
0c24b290 171
c2cf2042
LB
172Then make your changes. For example, if Leon Brocard changes his name
173to Orange Brocard, we should change his name in the AUTHORS file:
174
175 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
176
177You can see what files are changed:
178
179 % git status
f755e97d 180 # On branch orange
c2cf2042
LB
181 # Changes to be committed:
182 # (use "git reset HEAD <file>..." to unstage)
183 #
2699d634 184 # modified: AUTHORS
c2cf2042
LB
185 #
186
c2cf2042
LB
187And you can see the changes:
188
189 % git diff
190 diff --git a/AUTHORS b/AUTHORS
191 index 293dd70..722c93e 100644
192 --- a/AUTHORS
193 +++ b/AUTHORS
7df2e4bc 194 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
c2cf2042
LB
195 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
196 Leif Huhn <leif@hale.dkstat.com>
197 Len Johnson <lenjay@ibm.net>
198 -Leon Brocard <acme@astray.com>
199 +Orange Brocard <acme@astray.com>
200 Les Peters <lpeters@aol.net>
201 Lesley Binks <lesley.binks@gmail.com>
202 Lincoln D. Stein <lstein@cshl.org>
203
04c692a8 204Now commit your change locally:
77471e41 205
04c692a8
DR
206 % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
207 Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
208 1 files changed, 1 insertions(+), 1 deletions(-)
77471e41 209
04c692a8
DR
210The C<-a> option is used to include all files that git tracks that you
211have changed. If at this time, you only want to commit some of the
212files you have worked on, you can omit the C<-a> and use the command
213C<S<git add I<FILE ...>>> before doing the commit. C<S<git add
214--interactive>> allows you to even just commit portions of files
215instead of all the changes in them.
77471e41 216
04c692a8
DR
217The C<-m> option is used to specify the commit message. If you omit it,
218git will open a text editor for you to compose the message
219interactively. This is useful when the changes are more complex than
220the sample given here, and, depending on the editor, to know that the
221first line of the commit message doesn't exceed the 50 character legal
222maximum.
77471e41 223
04c692a8
DR
224Once you've finished writing your commit message and exited your
225editor, git will write your change to disk and tell you something like
226this:
77471e41 227
04c692a8
DR
228 Created commit daf8e63: explain git status and stuff about remotes
229 1 files changed, 83 insertions(+), 3 deletions(-)
c2cf2042 230
04c692a8 231If you re-run C<git status>, you should see something like this:
c2cf2042 232
04c692a8
DR
233 % git status
234 # On branch blead
235 # Your branch is ahead of 'origin/blead' by 2 commits.
236 #
237 # Untracked files:
238 # (use "git add <file>..." to include in what will be committed)
239 #
240 # deliberate.untracked
241 nothing added to commit but untracked files present (use "git add" to track)
2be70973 242
04c692a8
DR
243When in doubt, before you do anything else, check your status and read
244it carefully, many questions are answered directly by the git status
245output.
2be70973 246
dc3c3040
GA
247You can examine your last commit with:
248
249 % git show HEAD
250
251and if you are not happy with either the description or the patch
c26da522 252itself you can fix it up by editing the files once more and then issue:
dc3c3040
GA
253
254 % git commit -a --amend
255
c2cf2042
LB
256Now you should create a patch file for all your local changes:
257
f15b1f22 258 % git format-patch -M origin..
c2cf2042
LB
259 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
260
e001c712 261You should now send an email to
dce3ee48
AB
262L<perlbug@perl.org|mailto:perlbug@perl.org> with a description of your
263changes, and include this patch file as an attachment. In addition to
77db6475 264being tracked by RT, mail to perlbug will automatically be forwarded to
04c692a8
DR
265perl5-porters (with manual moderation, so please be patient). You
266should only send patches to
267L<perl5-porters@perl.org|mailto:perl5-porters@perl.org> directly if the
268patch is not ready to be applied, but intended for discussion.
64a8e22b
AB
269
270See the next section for how to configure and use git to send these
271emails for you.
c2cf2042 272
b1fccde5
LB
273If you want to delete your temporary branch, you may do so with:
274
275 % git checkout blead
276 % git branch -d orange
277 error: The branch 'orange' is not an ancestor of your current HEAD.
278 If you are sure you want to delete it, run 'git branch -D orange'.
279 % git branch -D orange
280 Deleted branch orange.
7df2e4bc 281
04c692a8
DR
282=head2 Committing your changes
283
6a6d7b97 284Assuming that you'd like to commit all the changes you've made as a
04c692a8
DR
285single atomic unit, run this command:
286
287 % git commit -a
288
289(That C<-a> tells git to add every file you've changed to this commit.
290New files aren't automatically added to your commit when you use
291C<commit -a> If you want to add files or to commit some, but not all of
292your changes, have a look at the documentation for C<git add>.)
293
294Git will start up your favorite text editor, so that you can craft a
295commit message for your change. See L<perlhack/Commit message> for more
296information about what makes a good commit message.
297
298Once you've finished writing your commit message and exited your
299editor, git will write your change to disk and tell you something like
300this:
301
302 Created commit daf8e63: explain git status and stuff about remotes
303 1 files changed, 83 insertions(+), 3 deletions(-)
304
305If you re-run C<git status>, you should see something like this:
306
307 % git status
308 # On branch blead
309 # Your branch is ahead of 'origin/blead' by 2 commits.
310 #
311 # Untracked files:
312 # (use "git add <file>..." to include in what will be committed)
313 #
314 # deliberate.untracked
315 nothing added to commit but untracked files present (use "git add" to track)
316
317When in doubt, before you do anything else, check your status and read
318it carefully, many questions are answered directly by the git status
319output.
320
2d5f1d01
DG
321=head2 Using git to send patch emails
322
04c692a8
DR
323Please read L<perlhack> first in order to figure out where your patches
324should be sent.
325
64a8e22b
AB
326In your ~/git/perl repository, set the destination email to perl's bug
327tracker:
328
329 $ git config sendemail.to perlbug@perl.org
330
04c692a8 331Or maybe perl5-porters:
2d5f1d01
DG
332
333 $ git config sendemail.to perl5-porters@perl.org
334
335Then you can use git directly to send your patch emails:
336
337 $ git send-email 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
338
333f8875
VP
339You may need to set some configuration variables for your particular
340email service provider. For example, to set your global git config to
341send email via a gmail account:
2d5f1d01
DG
342
343 $ git config --global sendemail.smtpserver smtp.gmail.com
344 $ git config --global sendemail.smtpssl 1
345 $ git config --global sendemail.smtpuser YOURUSERNAME@gmail.com
346
333f8875 347With this configuration, you will be prompted for your gmail password
04c692a8 348when you run 'git send-email'. You can also configure
333f8875
VP
349C<sendemail.smtppass> with your password if you don't care about having
350your password in the .gitconfig file.
2d5f1d01 351
a44f43ac
RGS
352=head2 A note on derived files
353
354Be aware that many files in the distribution are derivative--avoid
0549aefb 355patching them, because git won't see the changes to them, and the build
04c692a8 356process will overwrite them. Patch the originals instead. Most
0549aefb 357utilities (like perldoc) are in this category, i.e. patch
77db6475
LB
358F<utils/perldoc.PL> rather than F<utils/perldoc>. Similarly, don't
359create patches for files under $src_root/ext from their copies found in
04c692a8 360$install_root/lib. If you are unsure about the proper location of a
0549aefb
LB
361file that may have gotten copied while building the source
362distribution, consult the C<MANIFEST>.
a44f43ac 363
04c692a8 364=head2 Cleaning a working directory
b0d36535 365
6acba58e 366The command C<git clean> can with varying arguments be used as a
dc3c3040 367replacement for C<make clean>.
b0d36535
YO
368
369To reset your working directory to a pristine condition you can do:
370
e0b2b458 371 % git clean -dxf
b0d36535
YO
372
373However, be aware this will delete ALL untracked content. You can use
374
e0b2b458 375 % git clean -Xf
b0d36535 376
6acba58e
LB
377to remove all ignored untracked files, such as build and test
378byproduct, but leave any manually created files alone.
b0d36535 379
0549aefb 380If you only want to cancel some uncommitted edits, you can use C<git
c26da522
LB
381checkout> and give it a list of files to be reverted, or C<git checkout
382-f> to revert them all.
f755e97d
RGS
383
384If you want to cancel one or several commits, you can use C<git reset>.
385
04c692a8 386=head2 Bisecting
d82a90c1 387
6acba58e
LB
388C<git> provides a built-in way to determine, with a binary search in
389the history, which commit should be blamed for introducing a given bug.
d82a90c1 390
6acba58e 391Suppose that we have a script F<~/testcase.pl> that exits with C<0>
77db6475
LB
392when some behaviour is correct, and with C<1> when it's faulty. You
393need an helper script that automates building C<perl> and running the
6acba58e 394testcase:
d82a90c1
VP
395
396 % cat ~/run
397 #!/bin/sh
398 git clean -dxf
a4583001
AB
399
400 # If you get './makedepend: 1: Syntax error: Unterminated quoted
401 # string' when bisecting versions of perl older than 5.9.5 this hack
402 # will work around the bug in makedepend.SH which was fixed in
ccf3535a 403 # version 96a8704c. Make sure to comment out 'git checkout makedepend.SH'
a4583001
AB
404 # below too.
405 git show blead:makedepend.SH > makedepend.SH
406
d82a90c1 407 # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
1d5fe431
MB
408 # if Encode is not needed for the test, you can speed up the bisect by
409 # excluding it from the runs with -Dnoextensions=Encode
c0d1ef72
MB
410 sh Configure -des -Dusedevel -Doptimize="-g"
411 test -f config.sh || exit 125
412 # Correct makefile for newer GNU gcc
413 perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile
414 # if you just need miniperl, replace test_prep with miniperl
d7923bfe 415 make test_prep
68814ba4 416 [ -x ./perl ] || exit 125
d82a90c1 417 ./perl -Ilib ~/testcase.pl
c0d1ef72 418 ret=$?
7930c68b 419 [ $ret -gt 127 ] && ret=127
cfe91bfa 420 # git checkout makedepend.SH
c0d1ef72
MB
421 git clean -dxf
422 exit $ret
d82a90c1 423
6acba58e
LB
424This script may return C<125> to indicate that the corresponding commit
425should be skipped. Otherwise, it returns the status of
426F<~/testcase.pl>.
d82a90c1 427
bdaf0bc6 428You first enter in bisect mode with:
d82a90c1
VP
429
430 % git bisect start
431
6acba58e
LB
432For example, if the bug is present on C<HEAD> but wasn't in 5.10.0,
433C<git> will learn about this when you enter:
d82a90c1
VP
434
435 % git bisect bad
436 % git bisect good perl-5.10.0
437 Bisecting: 853 revisions left to test after this
438
6acba58e 439This results in checking out the median commit between C<HEAD> and
bdaf0bc6 440C<perl-5.10.0>. You can then run the bisecting process with:
d82a90c1
VP
441
442 % git bisect run ~/run
443
444When the first bad commit is isolated, C<git bisect> will tell you so:
445
446 ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
447 commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
448 Author: Dave Mitchell <davem@fdisolutions.com>
449 Date: Sat Feb 9 14:56:23 2008 +0000
450
9469eb4a 451 [perl #49472] Attributes + Unknown Error
d82a90c1
VP
452 ...
453
454 bisect run success
455
6acba58e
LB
456You can peek into the bisecting process with C<git bisect log> and
457C<git bisect visualize>. C<git bisect reset> will get you out of bisect
458mode.
d82a90c1 459
6acba58e
LB
460Please note that the first C<good> state must be an ancestor of the
461first C<bad> state. If you want to search for the commit that I<solved>
462some bug, you have to negate your test case (i.e. exit with C<1> if OK
463and C<0> if not) and still mark the lower bound as C<good> and the
464upper as C<bad>. The "first bad commit" has then to be understood as
465the "first commit where the bug is solved".
d82a90c1 466
6acba58e
LB
467C<git help bisect> has much more information on how you can tweak your
468binary searches.
feb5e972 469
04c692a8 470=head1 Topic branches and rewriting history
9d68b7ed 471
04c692a8
DR
472Individual committers should create topic branches under
473B<yourname>/B<some_descriptive_name>. Other committers should check
474with a topic branch's creator before making any change to it.
03050721 475
04c692a8
DR
476The simplest way to create a remote topic branch that works on all
477versions of git is to push the current head as a new branch on the
478remote, then check it out locally:
03050721 479
04c692a8
DR
480 $ branch="$yourname/$some_descriptive_name"
481 $ git push origin HEAD:$branch
482 $ git checkout -b $branch origin/$branch
03050721 483
04c692a8 484Users of git 1.7 or newer can do it in a more obvious manner:
03050721 485
04c692a8
DR
486 $ branch="$yourname/$some_descriptive_name"
487 $ git checkout -b $branch
488 $ git push origin -u $branch
03050721 489
04c692a8
DR
490If you are not the creator of B<yourname>/B<some_descriptive_name>, you
491might sometimes find that the original author has edited the branch's
492history. There are lots of good reasons for this. Sometimes, an author
493might simply be rebasing the branch onto a newer source point.
494Sometimes, an author might have found an error in an early commit which
495they wanted to fix before merging the branch to blead.
c26da522 496
04c692a8
DR
497Currently the master repository is configured to forbid
498non-fast-forward merges. This means that the branches within can not be
499rebased and pushed as a single step.
c26da522 500
04c692a8
DR
501The only way you will ever be allowed to rebase or modify the history
502of a pushed branch is to delete it and push it as a new branch under
503the same name. Please think carefully about doing this. It may be
504better to sequentially rename your branches so that it is easier for
505others working with you to cherry-pick their local changes onto the new
506version. (XXX: needs explanation).
c26da522 507
04c692a8
DR
508If you want to rebase a personal topic branch, you will have to delete
509your existing topic branch and push as a new version of it. You can do
510this via the following formula (see the explanation about C<refspec>'s
511in the git push documentation for details) after you have rebased your
512branch:
c26da522 513
04c692a8
DR
514 # first rebase
515 $ git checkout $user/$topic
516 $ git fetch
517 $ git rebase origin/blead
c26da522 518
04c692a8
DR
519 # then "delete-and-push"
520 $ git push origin :$user/$topic
521 $ git push origin $user/$topic
c26da522 522
04c692a8
DR
523B<NOTE:> it is forbidden at the repository level to delete any of the
524"primary" branches. That is any branch matching
525C<m!^(blead|maint|perl)!>. Any attempt to do so will result in git
526producing an error like this:
c26da522 527
04c692a8
DR
528 $ git push origin :blead
529 *** It is forbidden to delete blead/maint branches in this repository
530 error: hooks/update exited with error code 1
531 error: hook declined to update refs/heads/blead
532 To ssh://perl5.git.perl.org/perl
533 ! [remote rejected] blead (hook declined)
534 error: failed to push some refs to 'ssh://perl5.git.perl.org/perl'
c26da522 535
04c692a8
DR
536As a matter of policy we do B<not> edit the history of the blead and
537maint-* branches. If a typo (or worse) sneaks into a commit to blead or
538maint-*, we'll fix it in another commit. The only types of updates
539allowed on these branches are "fast-forward's", where all history is
540preserved.
2bab0636 541
04c692a8
DR
542Annotated tags in the canonical perl.git repository will never be
543deleted or modified. Think long and hard about whether you want to push
544a local tag to perl.git before doing so. (Pushing unannotated tags is
545not allowed.)
2bab0636 546
feb5e972 547=head2 Grafts
c26da522 548
04c692a8
DR
549The perl history contains one mistake which was not caught in the
550conversion: a merge was recorded in the history between blead and
551maint-5.10 where no merge actually occurred. Due to the nature of git,
552this is now impossible to fix in the public repository. You can remove
553this mis-merge locally by adding the following line to your
554C<.git/info/grafts> file:
c26da522 555
04c692a8 556 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930
c26da522 557
04c692a8
DR
558It is particularly important to have this graft line if any bisecting
559is done in the area of the "merge" in question.
ce2a8773 560
04c692a8
DR
561=head1 WRITE ACCESS TO THE GIT REPOSITORY
562
563Once you have write access, you will need to modify the URL for the
564origin remote to enable pushing. Edit F<.git/config> with the
565git-config(1) command:
566
567 % git config remote.origin.url ssh://perl5.git.perl.org/perl.git
568
569You can also set up your user name and e-mail address. Most people do
570this once globally in their F<~/.gitconfig> by doing something like:
571
572 % git config --global user.name "Ævar Arnfjörð Bjarmason"
573 % git config --global user.email avarab@gmail.com
574
575However if you'd like to override that just for perl then execute then
576execute something like the following in F<perl>:
577
578 % git config user.email avar@cpan.org
579
580It is also possible to keep C<origin> as a git remote, and add a new
581remote for ssh access:
582
583 % git remote add camel perl5.git.perl.org:/perl.git
584
585This allows you to update your local repository by pulling from
586C<origin>, which is faster and doesn't require you to authenticate, and
587to push your changes back with the C<camel> remote:
588
589 % git fetch camel
590 % git push camel
591
592The C<fetch> command just updates the C<camel> refs, as the objects
593themselves should have been fetched when pulling from C<origin>.
04baf1ff 594
04c692a8
DR
595=head1 Accepting a patch
596
597If you have received a patch file generated using the above section,
598you should try out the patch.
599
600First we need to create a temporary new branch for these changes and
601switch into it:
602
603 % git checkout -b experimental
604
605Patches that were formatted by C<git format-patch> are applied with
606C<git am>:
607
608 % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
609 Applying Rename Leon Brocard to Orange Brocard
610
611If just a raw diff is provided, it is also possible use this two-step
612process:
613
614 % git apply bugfix.diff
615 % git commit -a -m "Some fixing" --author="That Guy <that.guy@internets.com>"
edcf105d 616
04c692a8
DR
617Now we can inspect the change:
618
619 % git show HEAD
620 commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
621 Author: Leon Brocard <acme@astray.com>
622 Date: Fri Dec 19 17:02:59 2008 +0000
623
624 Rename Leon Brocard to Orange Brocard
625
626 diff --git a/AUTHORS b/AUTHORS
627 index 293dd70..722c93e 100644
628 --- a/AUTHORS
629 +++ b/AUTHORS
630 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
631 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
632 Leif Huhn <leif@hale.dkstat.com>
633 Len Johnson <lenjay@ibm.net>
634 -Leon Brocard <acme@astray.com>
635 +Orange Brocard <acme@astray.com>
636 Les Peters <lpeters@aol.net>
637 Lesley Binks <lesley.binks@gmail.com>
638 Lincoln D. Stein <lstein@cshl.org>
639
640If you are a committer to Perl and you think the patch is good, you can
641then merge it into blead then push it out to the main repository:
642
643 % git checkout blead
644 % git merge experimental
645 % git push
646
647If you want to delete your temporary branch, you may do so with:
648
649 % git checkout blead
650 % git branch -d experimental
651 error: The branch 'experimental' is not an ancestor of your current HEAD.
652 If you are sure you want to delete it, run 'git branch -D experimental'.
653 % git branch -D experimental
654 Deleted branch experimental.
655
656=head2 Committing to blead
657
658The 'blead' branch will become the next production release of Perl.
edcf105d
JV
659
660Before pushing I<any> local change to blead, it's incredibly important
661that you do a few things, lest other committers come after you with
662pitchforks and torches:
663
664=over
665
666=item *
667
04c692a8
DR
668Make sure you have a good commit message. See L<perlhack/Commit
669message> for details.
edcf105d
JV
670
671=item *
672
04c692a8
DR
673Run the test suite. You might not think that one typo fix would break a
674test file. You'd be wrong. Here's an example of where not running the
675suite caused problems. A patch was submitted that added a couple of
676tests to an existing .t. It couldn't possibly affect anything else, so
f76a37ee
KW
677no need to test beyond the single affected .t, right? But, the
678submitter's email address had changed since the last of their
04c692a8 679submissions, and this caused other tests to fail. Running the test
f76a37ee 680target given in the next item would have caught this problem.
edcf105d
JV
681
682=item *
683
684If you don't run the full test suite, at least C<make test_porting>.
685This will run basic sanity checks. To see which sanity checks, have a
686look in F<t/porting>.
687
cd78e84f
CB
688=item *
689
690If you make any changes that affect miniperl or core routines that have
04baf1ff 691different code paths for miniperl, be sure to run C<make minitest>.
cd78e84f
CB
692This will catch problems that even the full test suite will not catch
693because it runs a subset of tests under miniperl rather than perl.
694
edcf105d
JV
695=back
696
961bfa8c
RS
697=head3 On merging and rebasing
698
699Simple, one-off commits pushed to the 'blead' branch should be simple
700commits that apply cleanly. In other words, you should make sure your
701work is committed against the current position of blead, so that you can
702push back to the master repository without merging.
703
704Sometimes, blead will move while you're building or testing your
705changes. When this happens, your push will be rejected with a message
706like this:
707
708 To ssh://perl5.git.perl.org/perl.git
709 ! [rejected] blead -> blead (non-fast-forward)
710 error: failed to push some refs to 'ssh://perl5.git.perl.org/perl.git'
711 To prevent you from losing history, non-fast-forward updates were rejected
712 Merge the remote changes (e.g. 'git pull') before pushing again. See the
713 'Note about fast-forwards' section of 'git push --help' for details.
714
715When this happens, you can just I<rebase> your work against the new
716position of blead, like this (assuming your remote for the master
717repository is "p5p"):
718
719 $ git fetch p5p
720 $ git rebase p5p/blead
721
722You will see your commits being re-applied, and you will then be able to
c9d1da35 723push safely. More information about rebasing can be found in the
961bfa8c
RS
724documentation for the git-rebase(1) command.
725
726For larger sets of commits that only make sense together, or that would
727benefit from a summary of the set's purpose, you should use a merge
728commit. You should perform your work on a L<topic branch|/Topic
729branches and rewriting history>, which you should regularly rebase
730against blead to ensure that your code is not broken by blead moving.
bd3355a0
FC
731When you have finished your work, please perform a final rebase and
732test. Linear history is something that gets lost with every
733commit on blead, but a final rebase makes the history linear
734again, making it easier for future maintainers to see what has
735happened. Rebase as follows (assuming your work was on the
688cbe00 736branch C<< committer/somework >>):
961bfa8c 737
bd3355a0
FC
738 $ git checkout committer/somework
739 $ git rebase blead
740
741Then you can merge it into master like this:
742
961bfa8c
RS
743 $ git checkout blead
744 $ git merge --no-ff --no-commit committer/somework
745 $ git commit -a
746
747The switches above deserve explanation. C<--no-ff> indicates that even
748if all your work can be applied linearly against blead, a merge commit
749should still be prepared. This ensures that all your work will be shown
750as a side branch, with all its commits merged into the mainstream blead
751by the merge commit.
752
753C<--no-commit> means that the merge commit will be I<prepared> but not
754I<committed>. The commit is then actually performed when you run the
755next command, which will bring up your editor to describe the commit.
756Without C<--no-commit>, the commit would be made with nearly no useful
757message, which would greatly diminish the value of the merge commit as a
758placeholder for the work's description.
759
760When describing the merge commit, explain the purpose of the branch, and
761keep in mind that this description will probably be used by the
762eventual release engineer when reviewing the next perldelta document.
763
04c692a8 764=head2 Committing to maintenance versions
9d68b7ed 765
77db6475
LB
766Maintenance versions should only be altered to add critical bug fixes,
767see L<perlpolicy>.
7f4ffa9d 768
9d68b7ed
LB
769To commit to a maintenance version of perl, you need to create a local
770tracking branch:
771
772 % git checkout --track -b maint-5.005 origin/maint-5.005
773
0549aefb
LB
774This creates a local branch named C<maint-5.005>, which tracks the
775remote branch C<origin/maint-5.005>. Then you can pull, commit, merge
776and push as before.
b0d36535 777
f755e97d 778You can also cherry-pick commits from blead and another branch, by
0549aefb
LB
779using the C<git cherry-pick> command. It is recommended to use the
780B<-x> option to C<git cherry-pick> in order to record the SHA1 of the
781original commit in the new commit message.
f755e97d 782
04c692a8
DR
783Before pushing any change to a maint version, make sure you've
784satisfied the steps in L</Committing to blead> above.
edcf105d 785
04c692a8 786=head2 Merging from a branch via GitHub
bdaf0bc6 787
04c692a8
DR
788While we don't encourage the submission of patches via GitHub, that
789will still happen. Here is a guide to merging patches from a GitHub
790repository.
bdaf0bc6 791
04c692a8
DR
792 % git remote add avar git://github.com/avar/perl.git
793 % git fetch avar
041325d6 794
04c692a8 795Now you can see the differences between the branch and blead:
705c800c 796
04c692a8 797 % git diff avar/orange
705c800c 798
04c692a8 799And you can see the commits:
041325d6 800
04c692a8 801 % git log avar/orange
f755e97d 802
04c692a8
DR
803If you approve of a specific commit, you can cherry pick it:
804
805 % git cherry-pick 0c24b290ae02b2ab3304f51d5e11e85eb3659eae
806
807Or you could just merge the whole branch if you like it all:
808
809 % git merge avar/orange
810
811And then push back to the repository:
812
813 % git push
814
815=head2 A note on camel and dromedary
816
817The committers have SSH access to the two servers that serve
818C<perl5.git.perl.org>. One is C<perl5.git.perl.org> itself (I<camel>),
819which is the 'master' repository. The second one is
820C<users.perl5.git.perl.org> (I<dromedary>), which can be used for
821general testing and development. Dromedary syncs the git tree from
822camel every few minutes, you should not push there. Both machines also
823have a full CPAN mirror in /srv/CPAN, please use this. To share files
824with the general public, dromedary serves your ~/public_html/ as
825C<http://users.perl5.git.perl.org/~yourlogin/>
826
827These hosts have fairly strict firewalls to the outside. Outgoing, only
828rsync, ssh and git are allowed. For http and ftp, you can use
829http://webproxy:3128 as proxy. Incoming, the firewall tries to detect
830attacks and blocks IP addresses with suspicious activity. This
831sometimes (but very rarely) has false positives and you might get
832blocked. The quickest way to get unblocked is to notify the admins.
833
834These two boxes are owned, hosted, and operated by booking.com. You can
835reach the sysadmins in #p5p on irc.perl.org or via mail to
836C<perl5-porters@perl.org>.