pod/perlrepository.pod

   1 =for comment
   2 Consistent formatting of this file is achieved with:
   3   perl ./Porting/podtidy pod/perlrepository.pod
   4
   5 =head1 NAME
   6
   7 perlrepository - Using the Perl source repository
   8
   9 =head1 SYNOPSIS
  10
  11 All of Perl's source code is kept centrally in a Git repository at
  12 I<perl5.git.perl.org>. The repository contains many Perl revisions from
  13 Perl 1 onwards and all the revisions from Perforce, the version control
  14 system we were using previously. This repository is accessible in
  15 different ways.
  16
  17 The full repository takes up about 80MB of disk space. A check out of
  18 the blead branch (that is, the main development branch, which contains
  19 bleadperl, the development version of perl 5) takes up about 160MB of disk
  20 space (including the repository). A build of bleadperl takes up about 200MB
  21 (including the repository and the check out).
  22
  23 =head1 GETTING ACCESS TO THE REPOSITORY
  24
  25 =head2 READ ACCESS VIA THE WEB
  26
  27 You may access the repository over the web. This allows you to browse
  28 the tree, see recent commits, subscribe to RSS feeds for the changes,
  29 search for particular commits and more. You may access it at:
  30
  31   http://perl5.git.perl.org/perl.git
  32
  33 A mirror of the repository is found at:
  34
  35   http://github.com/github/perl
  36
  37 =head2 READ ACCESS VIA GIT
  38
  39 You will need a copy of Git for your computer. You can fetch a copy of
  40 the repository using the Git protocol (which uses port 9418):
  41
  42   git clone git://perl5.git.perl.org/perl.git perl-git
  43
  44 This clones the repository and makes a local copy in the F<perl-git>
  45 directory.
  46
  47 If your local network does not allow you to use port 9418, then you can
  48 fetch a copy of the repository over HTTP (this is slower):
  49
  50   git clone http://perl5.git.perl.org/perl.git perl-http
  51
  52 This clones the repository and makes a local copy in the F<perl-http>
  53 directory.
  54
  55 =head2 WRITE ACCESS TO THE REPOSITORY
  56
  57 If you are a committer, then you can fetch a copy of the repository
  58 that you can push back on with:
  59
  60   git clone ssh://perl5.git.perl.org/gitroot/perl.git perl-ssh
  61
  62 This clones the repository and makes a local copy in the F<perl-ssh>
  63 directory.
  64
  65 If you cloned using the git protocol, which is faster than ssh, then
  66 you will need to modify your config in order to enable pushing. Edit
  67 F<.git/config> where you will see something like:
  68
  69   [remote "origin"]
  70   url = git://perl5.git.perl.org/perl.git
  71
  72 change that to something like this:
  73
  74   [remote "origin"]
  75   url = ssh://perl5.git.perl.org/gitroot/perl.git
  76
  77 NOTE: there are symlinks set up so that the /gitroot is optional and
  78 since SSH is the default protocol you can actually shorten the "url" to
  79 C<perl5.git.perl.org:/perl.git>.
  80
  81 You 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
  86 It is also possible to keep C<origin> as a git remote, and add a new
  87 remote for ssh access:
  88
  89   % git remote add camel perl5.git.perl.org:/perl.git
  90
  91 This allows you to update your local repository by pulling from
  92 C<origin>, which is faster and doesn't require you to authenticate, and
  93 to push your changes back with the C<camel> remote:
  94
  95   % git fetch camel
  96   % git push camel
  97
  98 The C<fetch> command just updates the C<camel> refs, as the objects
  99 themselves should have been fetched when pulling from C<origin>.
 100
 101 The committers have access to 2 servers that serve perl5.git.perl.org. One is
 102 camel.booking.com, which is the 'master' repository. The perl5.git.perl.org IP
 103 address also lives on this machine. The second one is dromedary.booking.com,
 104 which can be used for general testing and development. Dromedary syncs the git
 105 tree from camel every few minutes, you should not push there. Both machines
 106 also have a full CPAN mirror. To share files with the general public, dromedary
 107 serves your ~/public_html/ as http://users.perl5.git.perl.org/~yourlogin/
 108
 109 =head1 OVERVIEW OF THE REPOSITORY
 110
 111 Once you have changed into the repository directory, you can inspect
 112 it.
 113
 114 After a clone the repository will contain a single local branch, which
 115 will be the current branch as well, as indicated by the asterisk.
 116
 117   % git branch
 118   * blead
 119
 120 Using the -a switch to C<branch> will also show the remote tracking
 121 branches in the repository:
 122
 123   % git branch -a
 124   * blead
 125     origin/HEAD
 126     origin/blead
 127   ...
 128
 129 The branches that begin with "origin" correspond to the "git remote"
 130 that you cloned from (which is named "origin"). Each branch on the
 131 remote will be exactly tracked by theses branches. You should NEVER do
 132 work on these remote tracking branches. You only ever do work in a
 133 local branch. Local branches can be configured to automerge (on pull)
 134 from a designated remote tracking branch. This is the case with the
 135 default branch C<blead> which will be configured to merge from the
 136 remote tracking branch C<origin/blead>.
 137
 138 You can see recent commits:
 139
 140   % git log
 141
 142 And pull new changes from the repository, and update your local
 143 repository (must be clean first)
 144
 145   % git pull
 146
 147 Assuming we are on the branch C<blead> immediately after a pull, this
 148 command would be more or less equivalent to:
 149
 150   % git fetch
 151   % git merge origin/blead
 152
 153 In fact if you want to update your local repository without touching
 154 your working directory you do:
 155
 156   % git fetch
 157
 158 And if you want to update your remote-tracking branches for all defined
 159 remotes simultaneously you can do
 160
 161   % git remote update
 162
 163 Neither of these last two commands will update your working directory,
 164 however both will update the remote-tracking branches in your
 165 repository.
 166
 167 To switch to another branch:
 168
 169   % git checkout origin/maint-5.8-dor
 170
 171 To make a local branch of a remote branch:
 172
 173   % git checkout -b maint-5.10 origin/maint-5.10
 174
 175 To switch back to blead:
 176
 177   % git checkout blead
 178
 179 =head2 FINDING OUT YOUR STATUS
 180
 181 The most common git command you will use will probably be
 182
 183   % git status
 184
 185 This command will produce as output a description of the current state
 186 of the repository, including modified files and unignored untracked
 187 files, and in addition it will show things like what files have been
 188 staged for the next commit, and usually some useful information about
 189 how to change things. For instance the following:
 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
 210 This shows that there were changes to this document staged for commit,
 211 and that there were further changes in the working directory not yet
 212 staged. It also shows that there was an untracked file in the working
 213 directory, and as you can see shows how to change all of this. It also
 214 shows that there is one commit on the working branch C<blead> which has
 215 not been pushed to the C<origin> remote yet. B<NOTE>: that this output
 216 is also what you see as a template if you do not provide a message to
 217 C<git commit>.
 218
 219 Assuming 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
 225 We 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
 237
 238 When in doubt, before you do anything else, check your status and read
 239 it carefully, many questions are answered directly by the git status
 240 output.
 241
 242 =head1 SUBMITTING A PATCH
 243
 244 If you have a patch in mind for Perl, you should first get a copy of
 245 the repository:
 246
 247   % git clone git://perl5.git.perl.org/perl.git perl-git
 248
 249 Then change into the directory:
 250
 251   % cd perl-git
 252
 253 Alternatively, if you already have a Perl repository, you should ensure
 254 that you're on the I<blead> branch, and your repository is up to date:
 255
 256   % git checkout blead
 257   % git pull
 258
 259 It's preferable to patch against the latest blead version, since
 260 this is where new development occurs for all changes other than critical
 261 bug fixes.  Critical bug fix patches should be made against the relevant
 262 maint branches, or should be submitted with a note indicating all the
 263 branches where the fix should be applied.
 264
 265 Now that we have everything up to date, we need to create a temporary
 266 new branch for these changes and switch into it:
 267
 268   % git checkout -b orange
 269
 270 which is the short form of
 271
 272   % git branch orange
 273   % git checkout orange
 274
 275 Then make your changes. For example, if Leon Brocard changes his name
 276 to Orange Brocard, we should change his name in the AUTHORS file:
 277
 278   % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
 279
 280 You can see what files are changed:
 281
 282   % git status
 283   # On branch orange
 284   # Changes to be committed:
 285   #   (use "git reset HEAD <file>..." to unstage)
 286   #
 287   #     modified:   AUTHORS
 288   #
 289
 290 And 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
 297   @@ -541,7 +541,7 @@    Lars Hecking                   <lhecking@nmrc.ucc.ie>
 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
 307 Now commit your change locally:
 308
 309   % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
 310   Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
 311    1 files changed, 1 insertions(+), 1 deletions(-)
 312
 313 You can examine your last commit with:
 314
 315   % git show HEAD
 316
 317 and if you are not happy with either the description or the patch
 318 itself you can fix it up by editing the files once more and then issue:
 319
 320   % git commit -a --amend
 321
 322 Now you should create a patch file for all your local changes:
 323
 324   % git format-patch origin
 325   0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
 326
 327 You should now send an email to perl5-porters@perl.org with a
 328 description of your changes, and include this patch file as an
 329 attachment.
 330
 331 If 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.
 339
 340 =head2 A note on derived files
 341
 342 Be aware that many files in the distribution are derivative--avoid
 343 patching them, because git won't see the changes to them, and the build
 344 process will overwrite them. Patch the originals instead.  Most
 345 utilities (like perldoc) are in this category, i.e. patch
 346 utils/perldoc.PL rather than utils/perldoc. Similarly, don't create
 347 patches 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
 349 file that may have gotten copied while building the source
 350 distribution, consult the C<MANIFEST>.
 351
 352 =head2 A note on binary files
 353
 354 Since the patch(1) utility cannot deal with binary files, it's
 355 important that you either avoid the use of binary files in your patch,
 356 generate the files dynamically, or that you encode any binary files
 357 using the F<uupacktool.pl> utility.
 358
 359 Assuming you needed to include a gzip-encoded file for a module's test
 360 suite, 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
 365 This will replace the C<t.gz> file with an encoded counterpart. During
 366 C<make test>, before any tests are run, perl's Makefile will restore
 367 all the C<.packed> files mentioned in the MANIFEST to their original
 368 name. This means that the test suite does not need to be aware of this
 369 packing scheme and will not need to be altered.
 370
 371 =head2 Getting your patch accepted
 372
 373 The first thing you should include with your patch is a description of
 374 the problem that the patch corrects.  If it is a code patch (rather
 375 than a documentation patch) you should also include a small test case
 376 that illustrates the bug (a patch to an existing test file is
 377 preferred).
 378
 379 If you are submitting a code patch there are several other things that
 380 you need to do.
 381
 382 =over 4
 383
 384 =item Comments, Comments, Comments
 385
 386 Be sure to adequately comment your code.  While commenting every line
 387 is unnecessary, anything that takes advantage of side effects of
 388 operators, that creates changes that will be felt outside of the
 389 function being patched, or that others may find confusing should be
 390 documented.  If you are going to err, it is better to err on the side
 391 of adding too many comments than too few.
 392
 393 =item Style
 394
 395 In general, please follow the particular style of the code you are
 396 patching.
 397
 398 In particular, follow these general guidelines for patching Perl
 399 sources:
 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
 421 When submitting a patch you should make every effort to also include an
 422 addition to perl's regression tests to properly exercise your patch.
 423 Your testsuite additions should generally follow these guidelines
 424 (courtesy of Gurusamy Sarathy <gsar@activestate.com>):
 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
 452 =head1 ACCEPTING A PATCH
 453
 454 If you have received a patch file generated using the above section,
 455 you should try out the patch.
 456
 457 First we need to create a temporary new branch for these changes and
 458 switch into it:
 459
 460   % git checkout -b experimental
 461
 462 Patches that were formatted by C<git format-patch> are applied with
 463 C<git am>:
 464
 465   % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
 466   Applying Rename Leon Brocard to Orange Brocard
 467
 468 If just a raw diff is provided, it is also possible use this two-step
 469 process:
 470
 471   % git apply bugfix.diff
 472   % git commit -a -m "Some fixing" --author="That Guy <that.guy@internets.com>"
 473
 474 Now we can inspect the change:
 475
 476   % git show HEAD
 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
 482
 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
 497 If you are a committer to Perl and you think the patch is good, you can
 498 then merge it into blead then push it out to the main repository:
 499
 500   % git checkout blead
 501   % git merge experimental
 502   % git push
 503
 504 If 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.
 512
 513 =head1 CLEANING A WORKING DIRECTORY
 514
 515 The command C<git clean> can with varying arguments be used as a
 516 replacement for C<make clean>.
 517
 518 To reset your working directory to a pristine condition you can do:
 519
 520   git clean -dxf
 521
 522 However, be aware this will delete ALL untracked content. You can use
 523
 524   git clean -Xf
 525
 526 to remove all ignored untracked files, such as build and test
 527 byproduct, but leave any  manually created files alone.
 528
 529 If you only want to cancel some uncommitted edits, you can use C<git
 530 checkout> and give it a list of files to be reverted, or C<git checkout
 531 -f> to revert them all.
 532
 533 If you want to cancel one or several commits, you can use C<git reset>.
 534
 535 =head1 BISECTING
 536
 537 C<git> provides a built-in way to determine, with a binary search in
 538 the history, which commit should be blamed for introducing a given bug.
 539
 540 Suppose that we have a script F<~/testcase.pl> that exits with C<0>
 541 when some behaviour is correct, and with C<1> when it's faulty. We need
 542 an helper script that automates building C<perl> and running the
 543 testcase:
 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
 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
 556   ./perl -Ilib ~/testcase.pl
 557   ret=$?
 558   git clean -dxf
 559   exit $ret
 560
 561 This script may return C<125> to indicate that the corresponding commit
 562 should be skipped. Otherwise, it returns the status of
 563 F<~/testcase.pl>.
 564
 565 We first enter in bisect mode with:
 566
 567   % git bisect start
 568
 569 For example, if the bug is present on C<HEAD> but wasn't in 5.10.0,
 570 C<git> will learn about this when you enter:
 571
 572   % git bisect bad
 573   % git bisect good perl-5.10.0
 574   Bisecting: 853 revisions left to test after this
 575
 576 This results in checking out the median commit between C<HEAD> and
 577 C<perl-5.10.0>. We can then run the bisecting process with:
 578
 579   % git bisect run ~/run
 580
 581 When 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
 588       [perl #49472] Attributes + Unknown Error
 589       ...
 590
 591   bisect run success
 592
 593 You can peek into the bisecting process with C<git bisect log> and
 594 C<git bisect visualize>. C<git bisect reset> will get you out of bisect
 595 mode.
 596
 597 Please note that the first C<good> state must be an ancestor of the
 598 first C<bad> state. If you want to search for the commit that I<solved>
 599 some bug, you have to negate your test case (i.e. exit with C<1> if OK
 600 and C<0> if not) and still mark the lower bound as C<good> and the
 601 upper as C<bad>. The "first bad commit" has then to be understood as
 602 the "first commit where the bug is solved".
 603
 604 C<git help bisect> has much more information on how you can tweak your
 605 binary searches.
 606
 607 =head1 SUBMITTING A PATCH VIA GITHUB
 608
 609 GitHub is a website that makes it easy to fork and publish projects
 610 with Git. First you should set up a GitHub account and log in.
 611
 612 Perl's git repository is mirrored on GitHub at this page:
 613
 614   http://github.com/github/perl/tree/blead
 615
 616 Visit the page and click the "fork" button. This clones the Perl git
 617 repository for you and provides you with "Your Clone URL" from which
 618 you should clone:
 619
 620   % git clone git@github.com:USERNAME/perl.git perl-github
 621
 622 We 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
 629   % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
 630   % git push origin orange
 631
 632 The orange branch has been pushed to GitHub, so you should now send an
 633 email to perl5-porters@perl.org with a description of your changes and
 634 the following information:
 635
 636   http://github.com/USERNAME/perl/tree/orange
 637   git@github.com:USERNAME/perl.git branch orange
 638
 639 =head1 MERGING FROM A BRANCH VIA GITHUB
 640
 641 If someone has provided a branch via GitHub and you are a committer,
 642 you should use the following in your perl-ssh directory:
 643
 644   % git remote add dandv git://github.com/dandv/perl.git
 645   % git fetch
 646
 647 Now you can see the differences between the branch and blead:
 648
 649   % git diff dandv/blead
 650
 651 And you can see the commits:
 652
 653   % git log dandv/blead
 654
 655 If you approve of a specific commit, you can cherry pick it:
 656
 657   % git cherry-pick 3adac458cb1c1d41af47fc66e67b49c8dec2323f
 658
 659 Or you could just merge the whole branch if you like it all:
 660
 661   % git merge dandv/blead
 662
 663 And then push back to the repository:
 664
 665   % git push
 666
 667 =head1 COMMITTING TO MAINTENANCE VERSIONS
 668
 669 Maintenance versions should only be altered to add critical bug fixes.
 670
 671 To commit to a maintenance version of perl, you need to create a local
 672 tracking branch:
 673
 674   % git checkout --track -b maint-5.005 origin/maint-5.005
 675
 676 This creates a local branch named C<maint-5.005>, which tracks the
 677 remote branch C<origin/maint-5.005>. Then you can pull, commit, merge
 678 and push as before.
 679
 680 You can also cherry-pick commits from blead and another branch, by
 681 using the C<git cherry-pick> command. It is recommended to use the
 682 B<-x> option to C<git cherry-pick> in order to record the SHA1 of the
 683 original commit in the new commit message.
 684
 685 =head1 SEE ALSO
 686
 687 The git documentation, accessible via C<git help command>.
 688