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/mirrors/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 at least 4x 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/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 the URL for the origin remote to enable
61 pushing. To do that edit .git/config with git-config(1) like this:
62 % git config remote.origin.url ssh://perl5.git.perl.org/perl.git
64 You can also set up your user name and e-mail address. Most people do
66 this once globally in their ~/.gitconfig by doing something like:
67 % git config --global user.name "A~Xvar ArnfjA~XrA~X Bjarmason"
69 % git config --global user.email avarab@gmail.com
70 However if you'd like to override that just for perl then execute then
72 execute something like the following in perl-git:
73 % git config user.email avar@cpan.org
75 It is also possible to keep "origin" as a git remote, and add a new
77 remote for ssh access:
78 % git remote add camel perl5.git.perl.org:/perl.git
80 This allows you to update your local repository by pulling from
82 "origin", which is faster and doesn't require you to authenticate, and
83 to push your changes back with the "camel" remote:
84 % git fetch camel
86 % git push camel
87 The "fetch" command just updates the "camel" refs, as the objects
89 themselves should have been fetched when pulling from "origin".
90 A note on camel and dromedary
92 The committers have SSH access to the two servers that serve
93 "perl5.git.perl.org". One is "perl5.git.perl.org" itself (camel), which
94 is the 'master' repository. The second one is
95 "users.perl5.git.perl.org" (dromedary), which can be used for general
96 testing and development. Dromedary syncs the git tree from camel every
97 few minutes, you should not push there. Both machines also have a full
98 CPAN mirror in /srv/CPAN, please use this. To share files with the
99 general public, dromedary serves your ~/public_html/ as
100 "http://users.perl5.git.perl.org/~yourlogin/"
101 These hosts have fairly strict firewalls to the outside. Outgoing, only
103 rsync, ssh and git are allowed. For http and ftp, you can use
104 http://webproxy:3128 as proxy. Incoming, the firewall tries to detect
105 attacks and blocks IP addresses with suspicious activity. This
106 sometimes (but very rarely) has false positives and you might get
107 blocked. The quickest way to get unblocked is to notify the admins.
108 These two boxes are owned, hosted, and operated by booking.com. You can
110 reach the sysadmins in #p5p on irc.perl.org or via mail to
111 "perl5-porters@perl.org"
112
114 Once you have changed into the repository directory, you can inspect
115 it.
116 After a clone the repository will contain a single local branch, which
118 will be the current branch as well, as indicated by the asterisk.
119 % git branch
121 * blead
122 Using the -a switch to "branch" will also show the remote tracking
124 branches in the repository:
125 % git branch -a
127 * blead
128 origin/HEAD
129 origin/blead
130 ...
131 The branches that begin with "origin" correspond to the "git remote"
133 that you cloned from (which is named "origin"). Each branch on the
134 remote will be exactly tracked by theses branches. You should NEVER do
135 work on these remote tracking branches. You only ever do work in a
136 local branch. Local branches can be configured to automerge (on pull)
137 from a designated remote tracking branch. This is the case with the
138 default branch "blead" which will be configured to merge from the
139 remote tracking branch "origin/blead".
140 You can see recent commits:
142 % git log
144 And pull new changes from the repository, and update your local
146 repository (must be clean first)
147 % git pull
149 Assuming we are on the branch "blead" immediately after a pull, this
151 command would be more or less equivalent to:
152 % git fetch
154 % git merge origin/blead
155 In fact if you want to update your local repository without touching
157 your working directory you do:
158 % git fetch
160 And if you want to update your remote-tracking branches for all defined
162 remotes simultaneously you can do
163 % git remote update
165 Neither of these last two commands will update your working directory,
167 however both will update the remote-tracking branches in your
168 repository.
169 To make a local branch of a remote branch:
171 % git checkout -b maint-5.10 origin/maint-5.10
173 To switch back to blead:
175 % git checkout blead
177 Finding out your status
179 The most common git command you will use will probably be
180 % git status
182 This command will produce as output a description of the current state
184 of the repository, including modified files and unignored untracked
185 files, and in addition it will show things like what files have been
186 staged for the next commit, and usually some useful information about
187 how to change things. For instance the following:
188 $ git status
190 # On branch blead
191 # Your branch is ahead of 'origin/blead' by 1 commit.
192 #
193 # Changes to be committed:
194 # (use "git reset HEAD <file>..." to unstage)
195 #
196 # modified: pod/perlrepository.pod
197 #
198 # Changed but not updated:
199 # (use "git add <file>..." to update what will be committed)
200 #
201 # modified: pod/perlrepository.pod
202 #
203 # Untracked files:
204 # (use "git add <file>..." to include in what will be committed)
205 #
206 # deliberate.untracked
207 This shows that there were changes to this document staged for commit,
209 and that there were further changes in the working directory not yet
210 staged. It also shows that there was an untracked file in the working
211 directory, and as you can see shows how to change all of this. It also
212 shows that there is one commit on the working branch "blead" which has
213 not been pushed to the "origin" remote yet. NOTE: that this output is
214 also what you see as a template if you do not provide a message to "git
215 commit".
216 Assuming that you'd like to commit all the changes you've just made as
218 a a single atomic unit, run this command:
219 % git commit -a
221 (That "-a" tells git to add every file you've changed to this commit.
223 New files aren't automatically added to your commit when you use
224 "commit -a" If you want to add files or to commit some, but not all of
225 your changes, have a look at the documentation for "git add".)
226 Git will start up your favorite text editor, so that you can craft a
228 commit message for your change. See "Commit message" below for more
229 information about what makes a good commit message.
230 Once you've finished writing your commit message and exited your
232 editor, git will write your change to disk and tell you something like
233 this:
234 Created commit daf8e63: explain git status and stuff about remotes
236 1 files changed, 83 insertions(+), 3 deletions(-)
237 If you re-run "git status", you should see something like this:
239 % git status
241 # On branch blead
242 # Your branch is ahead of 'origin/blead' by 2 commits.
243 #
244 # Untracked files:
245 # (use "git add <file>..." to include in what will be committed)
246 #
247 # deliberate.untracked
248 nothing added to commit but untracked files present (use "git add" to track)
249 When in doubt, before you do anything else, check your status and read
251 it carefully, many questions are answered directly by the git status
252 output.
253
255 If you have a patch in mind for Perl, you should first get a copy of
256 the repository:
257 % git clone git://perl5.git.perl.org/perl.git perl-git
259 Then change into the directory:
261 % cd perl-git
263 Alternatively, if you already have a Perl repository, you should ensure
265 that you're on the blead branch, and your repository is up to date:
266 % git checkout blead
268 % git pull
269 It's preferable to patch against the latest blead version, since this
271 is where new development occurs for all changes other than critical bug
272 fixes. Critical bug fix patches should be made against the relevant
273 maint branches, or should be submitted with a note indicating all the
274 branches where the fix should be applied.
275 Now that we have everything up to date, we need to create a temporary
277 new branch for these changes and switch into it:
278 % git checkout -b orange
280 which is the short form of
282 % git branch orange
284 % git checkout orange
285 Creating a topic branch makes it easier for the maintainers to rebase
287 or merge back into the master blead for a more linear history. If you
288 don't work on a topic branch the maintainer has to manually cherry pick
289 your changes onto blead before they can be applied.
290 That'll get you scolded on perl5-porters, so don't do that. Be Awesome.
292 Then make your changes. For example, if Leon Brocard changes his name
294 to Orange Brocard, we should change his name in the AUTHORS file:
295 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
297 You can see what files are changed:
299 % git status
301 # On branch orange
302 # Changes to be committed:
303 # (use "git reset HEAD <file>..." to unstage)
304 #
305 # modified: AUTHORS
306 #
307 And you can see the changes:
309 % git diff
311 diff --git a/AUTHORS b/AUTHORS
312 index 293dd70..722c93e 100644
313 --- a/AUTHORS
314 +++ b/AUTHORS
315 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
316 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
317 Leif Huhn <leif@hale.dkstat.com>
318 Len Johnson <lenjay@ibm.net>
319 -Leon Brocard <acme@astray.com>
320 +Orange Brocard <acme@astray.com>
321 Les Peters <lpeters@aol.net>
322 Lesley Binks <lesley.binks@gmail.com>
323 Lincoln D. Stein <lstein@cshl.org>
324 Now commit your change locally:
326 % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
328 Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
329 1 files changed, 1 insertions(+), 1 deletions(-)
330 You can examine your last commit with:
332 % git show HEAD
334 and if you are not happy with either the description or the patch
336 itself you can fix it up by editing the files once more and then issue:
337 % git commit -a --amend
339 Now you should create a patch file for all your local changes:
341 % git format-patch -M origin..
343 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
344 You should now send an email to to perlbug@perl.org
346 <mailto:perlbug@perl.org> with a description of your changes, and
347 include this patch file as an attachment. In addition to being tracked
348 by RT, mail to perlbug will automatically be forwarded to
349 perl5-porters. You should only send patches to perl5-porters@perl.org
350 <mailto:perl5-porters@perl.org> directly if the patch is not ready to
351 be applied, but intended for discussion.
352 See the next section for how to configure and use git to send these
354 emails for you.
355 If you want to delete your temporary branch, you may do so with:
357 % git checkout blead
359 % git branch -d orange
360 error: The branch 'orange' is not an ancestor of your current HEAD.
361 If you are sure you want to delete it, run 'git branch -D orange'.
362 % git branch -D orange
363 Deleted branch orange.
364 Using git to send patch emails
366 In your ~/git/perl repository, set the destination email to perl's bug
367 tracker:
368 $ git config sendemail.to perlbug@perl.org
370 Or maybe perl5-porters (discussed above):
372 $ git config sendemail.to perl5-porters@perl.org
374 Then you can use git directly to send your patch emails:
376 $ git send-email 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
378 You may need to set some configuration variables for your particular
380 email service provider. For example, to set your global git config to
381 send email via a gmail account:
382 $ git config --global sendemail.smtpserver smtp.gmail.com
384 $ git config --global sendemail.smtpssl 1
385 $ git config --global sendemail.smtpuser YOURUSERNAME@gmail.com
386 With this configuration, you will be prompted for your gmail password
388 when you run 'git send-email'. You can also configure
389 "sendemail.smtppass" with your password if you don't care about having
390 your password in the .gitconfig file.
391 A note on derived files
393 Be aware that many files in the distribution are derivative--avoid
394 patching them, because git won't see the changes to them, and the build
395 process will overwrite them. Patch the originals instead. Most
396 utilities (like perldoc) are in this category, i.e. patch
397 utils/perldoc.PL rather than utils/perldoc. Similarly, don't create
398 patches for files under $src_root/ext from their copies found in
399 $install_root/lib. If you are unsure about the proper location of a
400 file that may have gotten copied while building the source
401 distribution, consult the "MANIFEST".
402 As a special case, several files are regenerated by 'make regen' if
404 your patch alters "embed.fnc". These are needed for compilation, but
405 are included in the distribution so that you can build perl without
406 needing another perl to generate the files. You must test with these
407 regenerated files, but it is preferred that you instead note that 'make
408 regen is needed' in both the email and the commit message, and submit
409 your patch without them. If you're submitting a series of patches, it
410 might be best to submit the regenerated changes immediately after the
411 source-changes that caused them, so as to have as little effect as
412 possible on the bisectability of your patchset.
413 Getting your patch accepted
415 If you are submitting a code patch there are several things that you
416 need to do.
417 Commit message
419 As you craft each patch you intend to submit to the Perl core, it's
420 important to write a good commit message.
421 The first line of the commit message should be a short description
423 and should skip the full stop. It should be no longer than the
424 subject line of an E-Mail, 50 characters being a good rule of
425 thumb.
426 A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ..)
428 will only display the first line (cut off at 50 characters) when
429 presenting commit summaries.
430 The commit message should include description of the problem that
432 the patch corrects or new functionality that the patch adds.
433 As a general rule of thumb, your commit message should let a
435 programmer with a reasonable familiarity with the Perl core quickly
436 understand what you were trying to do, how you were trying to do it
437 and why the change matters to Perl.
438 What
440 Your commit message should describe what part of the Perl core
441 you're changing and what you expect your patch to do.
442 Why Perhaps most importantly, your commit message should describe
444 why the change you are making is important. When someone looks
445 at your change in six months or six years, your intent should
446 be clear. If you're deprecating a feature with the intent of
447 later simplifying another bit of code, say so. If you're fixing
448 a performance problem or adding a new feature to support some
449 other bit of the core, mention that.
450 How While it's not necessary for documentation changes, new tests
452 or trivial patches, it's often worth explaining how your change
453 works. Even if it's clear to you today, it may not be clear to
454 a porter next month or next year.
455 A commit message isn't intended to take the place of comments in
457 your code. Commit messages should describe the change you made,
458 while code comments should describe the current state of the code.
459 If you've just implemented a new feature, complete with doc, tests
460 and well-commented code, a brief commit message will often suffice.
461 If, however, you've just changed a single character deep in the
462 parser or lexer, you might need to write a small novel to ensure
463 that future readers understand what you did and why you did it.
464 Comments, Comments, Comments
466 Be sure to adequately comment your code. While commenting every
467 line is unnecessary, anything that takes advantage of side effects
468 of operators, that creates changes that will be felt outside of the
469 function being patched, or that others may find confusing should be
470 documented. If you are going to err, it is better to err on the
471 side of adding too many comments than too few.
472 Style
474 In general, please follow the particular style of the code you are
475 patching.
476 In particular, follow these general guidelines for patching Perl
478 sources:
479 8-wide tabs (no exceptions!)
481 4-wide indents for code, 2-wide indents for nested CPP #defines
482 try hard not to exceed 79-columns
483 ANSI C prototypes
484 uncuddled elses and "K&R" style for indenting control constructs
485 no C++ style (//) comments
486 mark places that need to be revisited with XXX (and revisit often!)
487 opening brace lines up with "if" when conditional spans multiple
488 lines; should be at end-of-line otherwise
489 in function definitions, name starts in column 0 (return value is on
490 previous line)
491 single space after keywords that are followed by parens, no space
492 between function name and following paren
493 avoid assignments in conditionals, but if they're unavoidable, use
494 extra paren, e.g. "if (a && (b = c)) ..."
495 "return foo;" rather than "return(foo);"
496 "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
497 Testsuite
499 If your patch changes code (rather than just changing
500 documentation) you should also include one or more test cases which
501 illustrate the bug you're fixing or validate the new functionality
502 you're adding. In general, you should update an existing test file
503 rather than create a new one.
504 Your testsuite additions should generally follow these guidelines
506 (courtesy of Gurusamy Sarathy <gsar@activestate.com>):
507 Know what you're testing. Read the docs, and the source.
509 Tend to fail, not succeed.
510 Interpret results strictly.
511 Use unrelated features (this will flush out bizarre interactions).
512 Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
513 Avoid using hardcoded test numbers whenever possible (the
514 EXPECTED/GOT found in t/op/tie.t is much more maintainable,
515 and gives better failure reports).
516 Give meaningful error messages when a test fails.
517 Avoid using qx// and system() unless you are testing for them. If you
518 do use them, make sure that you cover _all_ perl platforms.
519 Unlink any temporary files you create.
520 Promote unforeseen warnings to errors with $SIG{__WARN__}.
521 Be sure to use the libraries and modules shipped with the version
522 being tested, not those that were already installed.
523 Add comments to the code explaining what you are testing for.
524 Make updating the '1..42' string unnecessary. Or make sure that
525 you update it.
526 Test _all_ behaviors of a given operator, library, or function:
527 - All optional arguments
528 - Return values in various contexts (boolean, scalar, list, lvalue)
529 - Use both global and lexical variables
530 - Don't forget the exceptional, pathological cases.
531
533 If you have received a patch file generated using the above section,
534 you should try out the patch.
535 First we need to create a temporary new branch for these changes and
537 switch into it:
538 % git checkout -b experimental
540 Patches that were formatted by "git format-patch" are applied with "git
542 am":
543 % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
545 Applying Rename Leon Brocard to Orange Brocard
546 If just a raw diff is provided, it is also possible use this two-step
548 process:
549 % git apply bugfix.diff
551 % git commit -a -m "Some fixing" --author="That Guy <that.guy@internets.com>"
552 Now we can inspect the change:
554 % git show HEAD
556 commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
557 Author: Leon Brocard <acme@astray.com>
558 Date: Fri Dec 19 17:02:59 2008 +0000
559 Rename Leon Brocard to Orange Brocard
561 diff --git a/AUTHORS b/AUTHORS
563 index 293dd70..722c93e 100644
564 --- a/AUTHORS
565 +++ b/AUTHORS
566 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
567 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
568 Leif Huhn <leif@hale.dkstat.com>
569 Len Johnson <lenjay@ibm.net>
570 -Leon Brocard <acme@astray.com>
571 +Orange Brocard <acme@astray.com>
572 Les Peters <lpeters@aol.net>
573 Lesley Binks <lesley.binks@gmail.com>
574 Lincoln D. Stein <lstein@cshl.org>
575 If you are a committer to Perl and you think the patch is good, you can
577 then merge it into blead then push it out to the main repository:
578 % git checkout blead
580 % git merge experimental
581 % git push
582 If you want to delete your temporary branch, you may do so with:
584 % git checkout blead
586 % git branch -d experimental
587 error: The branch 'experimental' is not an ancestor of your current HEAD.
588 If you are sure you want to delete it, run 'git branch -D experimental'.
589 % git branch -D experimental
590 Deleted branch experimental.
591
593 The command "git clean" can with varying arguments be used as a
594 replacement for "make clean".
595 To reset your working directory to a pristine condition you can do:
597 % git clean -dxf
599 However, be aware this will delete ALL untracked content. You can use
601 % git clean -Xf
603 to remove all ignored untracked files, such as build and test
605 byproduct, but leave any manually created files alone.
606 If you only want to cancel some uncommitted edits, you can use "git
608 checkout" and give it a list of files to be reverted, or "git checkout
609 -f" to revert them all.
610 If you want to cancel one or several commits, you can use "git reset".
612
614 "git" provides a built-in way to determine, with a binary search in the
615 history, which commit should be blamed for introducing a given bug.
616 Suppose that we have a script ~/testcase.pl that exits with 0 when some
618 behaviour is correct, and with 1 when it's faulty. You need an helper
619 script that automates building "perl" and running the testcase:
620 % cat ~/run
622 #!/bin/sh
623 git clean -dxf
624 # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
625 # if Encode is not needed for the test, you can speed up the bisect by
626 # excluding it from the runs with -Dnoextensions=Encode
627 sh Configure -des -Dusedevel -Doptimize="-g"
628 test -f config.sh || exit 125
629 # Correct makefile for newer GNU gcc
630 perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile
631 # if you just need miniperl, replace test_prep with miniperl
632 make -j4 test_prep
633 [ -x ./perl ] || exit 125
634 ./perl -Ilib ~/testcase.pl
635 ret=$?
636 [ $ret -gt 127 ] && ret=127
637 git clean -dxf
638 exit $ret
639 This script may return 125 to indicate that the corresponding commit
641 should be skipped. Otherwise, it returns the status of ~/testcase.pl.
642 You first enter in bisect mode with:
644 % git bisect start
646 For example, if the bug is present on "HEAD" but wasn't in 5.10.0,
648 "git" will learn about this when you enter:
649 % git bisect bad
651 % git bisect good perl-5.10.0
652 Bisecting: 853 revisions left to test after this
653 This results in checking out the median commit between "HEAD" and
655 "perl-5.10.0". You can then run the bisecting process with:
656 % git bisect run ~/run
658 When the first bad commit is isolated, "git bisect" will tell you so:
660 ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
662 commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
663 Author: Dave Mitchell <davem@fdisolutions.com>
664 Date: Sat Feb 9 14:56:23 2008 +0000
665 [perl #49472] Attributes + Unknown Error
667 ...
668 bisect run success
670 You can peek into the bisecting process with "git bisect log" and "git
672 bisect visualize". "git bisect reset" will get you out of bisect mode.
673 Please note that the first "good" state must be an ancestor of the
675 first "bad" state. If you want to search for the commit that solved
676 some bug, you have to negate your test case (i.e. exit with 1 if OK and
677 0 if not) and still mark the lower bound as "good" and the upper as
678 "bad". The "first bad commit" has then to be understood as the "first
679 commit where the bug is solved".
680 "git help bisect" has much more information on how you can tweak your
682 binary searches.
683
685 GitHub is a website that makes it easy to fork and publish projects
686 with Git. First you should set up a GitHub account and log in.
687 Perl's git repository is mirrored on GitHub at this page:
689 http://github.com/mirrors/perl/tree/blead
691 Visit the page and click the "fork" button. This clones the Perl git
693 repository for you and provides you with "Your Clone URL" from which
694 you should clone:
695 % git clone git@github.com:USERNAME/perl.git perl-github
697 The same patch as above, using github might look like this:
699 % cd perl-github
701 % git remote add upstream git://perl5.git.perl.org/perl.git
702 % git pull upstream blead
703 % git checkout -b orange
704 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
705 % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
706 % git push origin orange
707 The orange branch has been pushed to GitHub, so you should now send an
709 email (see "Submitting a patch") with a description of your changes and
710 the following information:
711 http://github.com/USERNAME/perl/tree/orange
713 git@github.com:USERNAME/perl.git branch orange
714
716 If someone has provided a branch via GitHub and you are a committer,
717 you should use the following in your perl-ssh directory:
718 % git remote add dandv git://github.com/dandv/perl.git
720 % git fetch dandv
721 Now you can see the differences between the branch and blead:
723 % git diff dandv/blead
725 And you can see the commits:
727 % git log dandv/blead
729 If you approve of a specific commit, you can cherry pick it:
731 % git cherry-pick 3adac458cb1c1d41af47fc66e67b49c8dec2323f
733 Or you could just merge the whole branch if you like it all:
735 % git merge dandv/blead
737 And then push back to the repository:
739 % git push
741
743 Individual committers should create topic branches under
744 yourname/some_descriptive_name. Other committers should check with a
745 topic branch's creator before making any change to it.
746 The simplest way to create a remote topic branch that works on all
748 versions of git is to push the current head as a new branch on the
749 remote, then check it out locally:
750 $ branch="$yourname/$some_descriptive_name"
752 $ git push origin HEAD:$branch
753 $ git checkout -b $branch origin/$branch
754 Users of git 1.7 or newer can do it in a more obvious manner:
756 $ branch="$yourname/$some_descriptive_name"
758 $ git checkout -b $branch
759 $ git push origin -u $branch
760 If you are not the creator of yourname/some_descriptive_name, you might
762 sometimes find that the original author has edited the branch's
763 history. There are lots of good reasons for this. Sometimes, an author
764 might simply be rebasing the branch onto a newer source point.
765 Sometimes, an author might have found an error in an early commit which
766 they wanted to fix before merging the branch to blead.
767 Currently the master repository is configured to forbid non-fast-
769 forward merges. This means that the branches within can not be rebased
770 and pushed as a single step.
771 The only way you will ever be allowed to rebase or modify the history
773 of a pushed branch is to delete it and push it as a new branch under
774 the same name. Please think carefully about doing this. It may be
775 better to sequentially rename your branches so that it is easier for
776 others working with you to cherry-pick their local changes onto the new
777 version. (XXX: needs explanation).
778 If you want to rebase a personal topic branch, you will have to delete
780 your existing topic branch and push as a new version of it. You can do
781 this via the following formula (see the explanation about "refspec"'s
782 in the git push documentation for details) after you have rebased your
783 branch:
784 # first rebase
786 $ git checkout $user/$topic
787 $ git fetch
788 $ git rebase origin/blead
789 # then "delete-and-push"
791 $ git push origin :$user/$topic
792 $ git push origin $user/$topic
793 NOTE: it is forbidden at the repository level to delete any of the
795 "primary" branches. That is any branch matching
796 "m!^(blead|maint|perl)!". Any attempt to do so will result in git
797 producing an error like this:
798 $ git push origin :blead
800 *** It is forbidden to delete blead/maint branches in this repository
801 error: hooks/update exited with error code 1
802 error: hook declined to update refs/heads/blead
803 To ssh://perl5.git.perl.org/perl
804 ! [remote rejected] blead (hook declined)
805 error: failed to push some refs to 'ssh://perl5.git.perl.org/perl'
806 As a matter of policy we do not edit the history of the blead and
808 maint-* branches. If a typo (or worse) sneaks into a commit to blead or
809 maint-*, we'll fix it in another commit. The only types of updates
810 allowed on these branches are "fast-forward's", where all history is
811 preserved.
812 Annotated tags in the canonical perl.git repository will never be
814 deleted or modified. Think long and hard about whether you want to push
815 a local tag to perl.git before doing so. (Pushing unannotated tags is
816 not allowed.)
817
819 Maintenance versions should only be altered to add critical bug fixes,
820 see perlpolicy.
821 To commit to a maintenance version of perl, you need to create a local
823 tracking branch:
824 % git checkout --track -b maint-5.005 origin/maint-5.005
826 This creates a local branch named "maint-5.005", which tracks the
828 remote branch "origin/maint-5.005". Then you can pull, commit, merge
829 and push as before.
830 You can also cherry-pick commits from blead and another branch, by
832 using the "git cherry-pick" command. It is recommended to use the -x
833 option to "git cherry-pick" in order to record the SHA1 of the original
834 commit in the new commit message.
835
837 The perl history contains one mistake which was not caught in the
838 conversion: a merge was recorded in the history between blead and
839 maint-5.10 where no merge actually occurred. Due to the nature of git,
840 this is now impossible to fix in the public repository. You can remove
841 this mis-merge locally by adding the following line to your
842 ".git/info/grafts" file:
843 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930
845 It is particularly important to have this graft line if any bisecting
847 is done in the area of the "merge" in question.
848
850 · The git documentation, accessible via the "git help" command
851 · perlpolicy - Perl core development policy
853perl v5.12.4 2011-06-20 PERLREPOSITORY(1)