disk space (including the repository). A build of bleadperl takes up
about 200MB (including the repository and the check out).
-=head1 GETTING ACCESS TO THE REPOSITORY
+=head1 Getting access to the repository
-=head2 READ ACCESS VIA THE WEB
+=head2 Read access via the web
You may access the repository over the web. This allows you to browse
the tree, see recent commits, subscribe to RSS feeds for the changes,
A mirror of the repository is found at:
- http://github.com/github/perl
+ http://github.com/mirrors/perl
-=head2 READ ACCESS VIA GIT
+=head2 Read access via Git
You will need a copy of Git for your computer. You can fetch a copy of
the repository using the Git protocol (which uses port 9418):
This clones the repository and makes a local copy in the F<perl-http>
directory.
-=head2 WRITE ACCESS TO THE REPOSITORY
+=head2 Write access to the repository
If you are a committer, then you can fetch a copy of the repository
that you can push back on with:
If you cloned using the git protocol, which is faster than ssh, then
you will need to modify the URL for the origin remote to enable
-pushing. To do that edit F<.git/config> with L<git-config(1)> like
+pushing. To do that edit F<.git/config> with git-config(1) like
this:
% git config remote.origin.url ssh://perl5.git.perl.org/perl.git
The C<fetch> command just updates the C<camel> refs, as the objects
themselves should have been fetched when pulling from C<origin>.
-=head2 A NOTE ON CAMEL AND DROMEDARY
+=head2 A note on camel and dromedary
The committers have SSH access to the two servers that serve
C<perl5.git.perl.org>. One is C<perl5.git.perl.org> itself (I<camel>),
reach the sysadmins in #p5p on irc.perl.org or via mail to
C<perl5-porters@perl.org>
-=head1 OVERVIEW OF THE REPOSITORY
+=head1 Overview of the repository
Once you have changed into the repository directory, you can inspect
it.
however both will update the remote-tracking branches in your
repository.
-To switch to another branch:
-
- % git checkout origin/maint-5.8-dor
-
To make a local branch of a remote branch:
% git checkout -b maint-5.10 origin/maint-5.10
% git checkout blead
-=head2 FINDING OUT YOUR STATUS
+=head2 Finding out your status
The most common git command you will use will probably be
it carefully, many questions are answered directly by the git status
output.
-=head1 SUBMITTING A PATCH
+=head1 Submitting a patch
If you have a patch in mind for Perl, you should first get a copy of
the repository:
Now you should create a patch file for all your local changes:
- % git format-patch origin
+ % git format-patch -M origin..
0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
-You should now send an email to perl5-porters@perl.org with a
-description of your changes, and include this patch file as an
-attachment. (See the next section for how to configure and use git to
-send these emails for you.)
+You should now send an email to either perlbug@perl.org or
+perl5-porters@perl.org with a description of your changes, and include
+this patch file as an attachment. The perlbug address is preferred,
+but use perl5-porters for patches intended for discussion.
+
+See the next section for how to configure and use git to send these
+emails for you.
If you want to delete your temporary branch, you may do so with:
=head2 Using git to send patch emails
-In your ~/git/perl repository, set the destination email to the
-perl5-porters mailing list.
+In your ~/git/perl repository, set the destination email to perl's bug
+tracker:
+
+ $ git config sendemail.to perlbug@perl.org
+
+Or maybe perl5-porters (discussed above):
$ git config sendemail.to perl5-porters@perl.org
patching them, because git won't see the changes to them, and the build
process will overwrite them. Patch the originals instead. Most
utilities (like perldoc) are in this category, i.e. patch
-utils/perldoc.PL rather than utils/perldoc. Similarly, don't create
+F<utils/perldoc.PL> rather than F<utils/perldoc>. Similarly, don't create
patches for files under $src_root/ext from their copies found in
$install_root/lib. If you are unsure about the proper location of a
file that may have gotten copied while building the source
As you craft each patch you intend to submit to the Perl core, it's
important to write a good commit message.
-Your commit message should start with a description of the problem that
-the patch corrects or new functionality that the patch adds.
+The first line of the commit message should be a short description and
+should skip the full stop. It should be no longer than the subject
+line of an E-Mail, 50 characters being a good rule of thumb.
+
+A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ..) will
+only display the first line (cut off at 50 characters) when presenting
+commit summaries.
+
+The commit message should include description of the problem that the
+patch corrects or new functionality that the patch adds.
As a general rule of thumb, your commit message should let a programmer
with a reasonable familiarity with the Perl core quickly understand what
=back
-=head1 ACCEPTING A PATCH
+=head1 Accepting a patch
If you have received a patch file generated using the above section,
you should try out the patch.
% git branch -D experimental
Deleted branch experimental.
-=head1 CLEANING A WORKING DIRECTORY
+=head1 Cleaning a working directory
The command C<git clean> can with varying arguments be used as a
replacement for C<make clean>.
If you want to cancel one or several commits, you can use C<git reset>.
-=head1 BISECTING
+=head1 Bisecting
C<git> provides a built-in way to determine, with a binary search in
the history, which commit should be blamed for introducing a given bug.
% cat ~/run
#!/bin/sh
git clean -dxf
+
+ # If you get './makedepend: 1: Syntax error: Unterminated quoted
+ # string' when bisecting versions of perl older than 5.9.5 this hack
+ # will work around the bug in makedepend.SH which was fixed in
+ # version 96a8704c. Make sure to comment out `git checkout makedepend.SH'
+ # below too.
+ git show blead:makedepend.SH > makedepend.SH
+
# If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
# if Encode is not needed for the test, you can speed up the bisect by
# excluding it from the runs with -Dnoextensions=Encode
# Correct makefile for newer GNU gcc
perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile
# if you just need miniperl, replace test_prep with miniperl
- make -j4 test_prep
+ make test_prep
[ -x ./perl ] || exit 125
./perl -Ilib ~/testcase.pl
ret=$?
[ $ret -gt 127 ] && ret=127
+ # git checkout makedepend.SH
git clean -dxf
exit $ret
C<git help bisect> has much more information on how you can tweak your
binary searches.
-=head1 SUBMITTING A PATCH VIA GITHUB
+=head1 Submitting a patch via GitHub
GitHub is a website that makes it easy to fork and publish projects
with Git. First you should set up a GitHub account and log in.
Perl's git repository is mirrored on GitHub at this page:
- http://github.com/github/perl/tree/blead
+ http://github.com/mirrors/perl/tree/blead
Visit the page and click the "fork" button. This clones the Perl git
repository for you and provides you with "Your Clone URL" from which
The same patch as above, using github might look like this:
% cd perl-github
- % git remote add upstream git://github.com/github/perl.git
+ % git remote add upstream git://perl5.git.perl.org/perl.git
% git pull upstream blead
% git checkout -b orange
% perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
% git push origin orange
The orange branch has been pushed to GitHub, so you should now send an
-email to perl5-porters@perl.org with a description of your changes and
-the following information:
+email (see L</Submitting a patch>) with a description of your changes
+and the following information:
http://github.com/USERNAME/perl/tree/orange
- git@github.com:USERNAME/perl.git branch orange
+ git://github.com/USERNAME/perl.git branch orange
-=head1 MERGING FROM A BRANCH VIA GITHUB
+=head1 Merging from a branch via GitHub
If someone has provided a branch via GitHub and you are a committer,
you should use the following in your perl-ssh directory:
- % git remote add dandv git://github.com/dandv/perl.git
- % git fetch
+ % git remote add avar git://github.com/avar/perl.git
+ % git fetch avar
Now you can see the differences between the branch and blead:
- % git diff dandv/blead
+ % git diff avar/orange
And you can see the commits:
- % git log dandv/blead
+ % git log avar/orange
If you approve of a specific commit, you can cherry pick it:
- % git cherry-pick 3adac458cb1c1d41af47fc66e67b49c8dec2323f
+ % git cherry-pick 0c24b290ae02b2ab3304f51d5e11e85eb3659eae
Or you could just merge the whole branch if you like it all:
- % git merge dandv/blead
+ % git merge avar/orange
And then push back to the repository:
% git push
-=head1 TOPIC BRANCHES AND REWRITING HISTORY
+=head1 Topic branches and rewriting history
Individual committers should create topic branches under
B<yourname>/B<some_descriptive_name>. Other committers should check
with a topic branch's creator before making any change to it.
+The simplest way to create a remote topic branch that works on all
+versions of git is to push the current head as a new branch on the
+remote, then check it out locally:
+
+ $ branch="$yourname/$some_descriptive_name"
+ $ git push origin HEAD:$branch
+ $ git checkout -b $branch origin/$branch
+
+Users of git 1.7 or newer can do it in a more obvious manner:
+
+ $ branch="$yourname/$some_descriptive_name"
+ $ git checkout -b $branch
+ $ git push origin -u $branch
+
If you are not the creator of B<yourname>/B<some_descriptive_name>, you
might sometimes find that the original author has edited the branch's
history. There are lots of good reasons for this. Sometimes, an author
a local tag to perl.git before doing so. (Pushing unannotated tags is
not allowed.)
-=head1 COMMITTING TO MAINTENANCE VERSIONS
+=head1 Committing to maintenance versions
-Maintenance versions should only be altered to add critical bug fixes.
+Maintenance versions should only be altered to add critical bug
+fixes, see L<perlpolicy>.
To commit to a maintenance version of perl, you need to create a local
tracking branch:
B<-x> option to C<git cherry-pick> in order to record the SHA1 of the
original commit in the new commit message.
-=head1 GRAFTS
+=head1 Grafts
The perl history contains one mistake which was not caught in the
conversion: a merge was recorded in the history between blead and
It is particularly important to have this graft line if any bisecting
is done in the area of the "merge" in question.
+=head1 SEE ALSO
+
+=over
+=item *
-=head1 SEE ALSO
+The git documentation, accessible via the C<git help> command
+
+=item *
-The git documentation, accessible via C<git help command>.
+L<perlpolicy> - Perl core development policy
+
+=back
+=cut
https://perl5.git.perl.org / perl5.git / blobdiff