diff options
author | H.Merijn Brand <h.m.brand@xs4all.nl> | 2008-12-23 18:10:54 +0100 |
---|---|---|
committer | H.Merijn Brand <h.m.brand@xs4all.nl> | 2008-12-23 18:10:54 +0100 |
commit | 235f84edeedd25ea878a5e9d8ee8490c1af72837 (patch) | |
tree | dbb15e3ccbd0ae9710bac1ab05ea65a586e85b4c | |
parent | 7f98bb4e5817790bc537b480552504b79734edd5 (diff) | |
parent | 6acba58e99cd9b39fe8819489c5ef1fba1528787 (diff) | |
download | perl-235f84edeedd25ea878a5e9d8ee8490c1af72837.tar.gz |
Merge branch 'blead' of camel.booking.com:/gitroot/perl into blead
-rw-r--r-- | MANIFEST | 1 | ||||
-rw-r--r-- | Porting/podtidy | 18 | ||||
-rw-r--r-- | pod/perlrepository.pod | 168 |
3 files changed, 125 insertions, 62 deletions
@@ -3525,6 +3525,7 @@ Porting/p4d2p Generate patch from p4 diff Porting/p4genpatch Generate patch from p4 change in repository (obsoletes p4desc) Porting/patching.pod How to report changes made to Perl Porting/patchls Flexible patch file listing utility +Porting/podtidy Reformat pod using Pod::Tidy Porting/pumpkin.pod Guidelines and hints for Perl maintainers Porting/README.y2038 Perl notes for the 2038 fix Porting/regcharclass.pl Generate regcharclass.h from inline data diff --git a/Porting/podtidy b/Porting/podtidy new file mode 100644 index 0000000000..a15b3786cf --- /dev/null +++ b/Porting/podtidy @@ -0,0 +1,18 @@ +#!perl +use strict; +use warnings; +use Pod::Tidy; + +# Reformat pod using Pod::Tidy + +# 72 is what fmt defaults to +$Text::Wrap::columns = 72; + +my $filename = shift || die "Usage podtidy [filename]"; + +Pod::Tidy::tidy_files( + files => [$filename], + verbose => 1, + inplace => 1, + nobackup => 1, +); diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod index 34d464e0af..384e290299 100644 --- a/pod/perlrepository.pod +++ b/pod/perlrepository.pod @@ -5,8 +5,8 @@ perlrepository - Using the Perl source repository =head1 SYNOPSIS All of Perl's source code is kept centrally in a Git repository. The -repository contains many Perl revisions from Perl 1 onwards and all -the revisions from Perforce, the version control system we were using +repository contains many Perl revisions from Perl 1 onwards and all the +revisions from Perforce, the version control system we were using previously. This repository is accessible in different ways. The full repository takes up about 80MB of disk space. A check out of @@ -45,8 +45,8 @@ directory. =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 are a committer, then you can fetch a copy of the repository +that you can push back on with: git clone ssh://perl5.git.perl.org/gitroot/perl.git perl-ssh @@ -54,8 +54,8 @@ This clones the repository and makes a local copy in the 'perl-ssh' directory. If you clone using git, which is faster than ssh, then you will need to -modify your config in order to enable pushing. Edit F<.git/config> where -you will see something like: +modify your config in order to enable pushing. Edit F<.git/config> +where you will see something like: [remote "origin"] url = git://perl5.git.perl.org/perl.git @@ -65,27 +65,33 @@ change that to something like this: [remote "origin"] url = ssh://perl5.git.perl.org/gitroot/perl.git -NOTE: there are symlinks set up so that the /gitroot is actually optional. +NOTE: there are symlinks set up so that the /gitroot is actually +optional. You can also set up your user name and e-mail address. For example % git config user.name "Leon Brocard" % git config user.email acme@astray.com -It is also possible to keep C<origin> as a git remote, and add a new remote for ssh access: +It is also possible to keep C<origin> as a git remote, and add a new +remote for ssh access: % git remote add camel user@camel:/gitroot/perl.git -This allows you to update your local repository by pulling from C<origin>, which is faster and doesn't require you to authentify, and to push your changes back with the C<camel> remote: +This allows you to update your local repository by pulling from +C<origin>, which is faster and doesn't require you to authentify, and +to push your changes back with the C<camel> remote: % git fetch camel % git push camel -The C<fetch> command just updates the C<camel> refs, as the objects themselves should have been fetched when pulling from C<origin>. +The C<fetch> command just updates the C<camel> refs, as the objects +themselves should have been fetched when pulling from C<origin>. =head1 OVERVIEW OF THE REPOSITORY -Once you have changed into the repository directory, you can inspect it. +Once you have changed into the repository directory, you can inspect +it. After a clone the repository will contain a single local branch, which @@ -94,8 +100,8 @@ will be the current branch as well, as indicated by the asterix. % git branch * blead -Using the -a switch to branch will also show the remote tracking branches in the -repository: +Using the -a switch to branch will also show the remote tracking +branches in the repository: % git branch -a * blead @@ -103,42 +109,43 @@ repository: origin/blead ... -The branches that begin with "origin" correspond to the "git remote" that -you cloned from (which is named "origin"). Each branch on the remote will -be exactly tracked by theses branches. You should NEVER do work on these -remote tracking branches. You only ever do work in a local branch. Local -branches can be configured to automerge (on pull) from a designated remote -tracking branch. This is the case with the default branch C<blead> which -will be configured to merge from the remote tracking branch -C<origin/blead>. +The branches that begin with "origin" correspond to the "git remote" +that you cloned from (which is named "origin"). Each branch on the +remote will be exactly tracked by theses branches. You should NEVER do +work on these remote tracking branches. You only ever do work in a +local branch. Local branches can be configured to automerge (on pull) +from a designated remote tracking branch. This is the case with the +default branch C<blead> which will be configured to merge from the +remote tracking branch C<origin/blead>. You can see recent commits: % git log -And pull new changes from the repository, and update your local repository -(must be clean first) +And pull new changes from the repository, and update your local +repository (must be clean first) % git pull -Assuming we are on the branch C<blead> immediately after a pull, this command -would be more or less equivalent to: +Assuming we are on the branch C<blead> immediately after a pull, this +command would be more or less equivalent to: % git fetch % git merge origin/blead -In fact if you want to update your local repository without touching your working -directory you do: +In fact if you want to update your local repository without touching +your working directory you do: % git fetch -And if you want to update your remote-tracking branches for all defined remotes -simultaneously you can do +And if you want to update your remote-tracking branches for all defined +remotes simultaneously you can do % git remote update -Neither of these last two commands will update your working directory, however -both will update the remote-tracking branches in your repository. +Neither of these last two commands will update your working directory, +however both will update the remote-tracking branches in your +repository. To switch to another branch: @@ -154,11 +161,11 @@ The most common git command you will use will probably be % git status -This command will produce as output a description of the current state of the -repository, including modified files and unignored untracked files, and in addition -it will show things like what files have been staged for the next commit, -and usually some useful information about how to change things. For instance the -following: +This command will produce as output a description of the current state +of the repository, including modified files and unignored untracked +files, and in addition it will show things like what files have been +staged for the next commit, and usually some useful information about +how to change things. For instance the following: $ git status # On branch blead @@ -179,13 +186,14 @@ following: # # deliberate.untracked -This shows that there were changes to this document staged for commit, and -that there were further changes in the working directory not yet staged. It -also shows that there was an untracked file in the working directory, and as -you can see shows how to change all of this. It also shows that there -is one commit on the working branch C<blead> which has not been pushed to the -C<origin> remote yet. B<NOTE>: that this output is also what you see as a -template if you do not provide a message to C<git commit>. +This shows that there were changes to this document staged for commit, +and that there were further changes in the working directory not yet +staged. It also shows that there was an untracked file in the working +directory, and as you can see shows how to change all of this. It also +shows that there is one commit on the working branch C<blead> which +has not been pushed to the C<origin> remote yet. B<NOTE>: that this +output is also what you see as a template if you do not provide a +message to C<git commit>. Assuming we commit all the mentioned changes above: @@ -206,8 +214,9 @@ We can re-run git status and see something like this: nothing added to commit but untracked files present (use "git add" to track) -When in doubt, before you do anything else, check your status and read it -carefully, many questions are answered directly by the git status output. +When in doubt, before you do anything else, check your status and read +it carefully, many questions are answered directly by the git status +output. =head1 SUBMITTING A PATCH @@ -220,15 +229,14 @@ Then change into the directory: % cd perl-git -Alternatively, if you already have a Perl repository, you should -ensure that you're on the I<blead> branch, and your repository -is up to date: +Alternatively, if you already have a Perl repository, you should ensure +that you're on the I<blead> branch, and your repository is up to date: % git checkout blead % git pull -Now that we have everything up to date, we need to create a temporary new -branch for these changes and switch into it: +Now that we have everything up to date, we need to create a temporary +new branch for these changes and switch into it: % git checkout -b orange @@ -304,11 +312,18 @@ switch into it: % git checkout -b experimental -Now we should apply the patch: +Patches that were formatted by C<git format-patch> are applied with +C<git am>: % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch Applying Rename Leon Brocard to Orange Brocard +If just a raw diff is provided, it is also possible use this two-step +process: + + % git apply bugfix.diff + % git commit -am "Some fixing" --author="That Guy <that.guy@internets.com>" + Now we can inspect the change: % git log @@ -352,7 +367,8 @@ If you want to delete your temporary branch, you may do so with: =head1 CLEANING A WORKING DIRECTORY -The command C<git clean> can with varying arguments be used as a replacement for make-clean. +The command C<git clean> can with varying arguments be used as a +replacement for make-clean. To reset your working directory to a pristine condition you can do: @@ -362,14 +378,18 @@ However, be aware this will delete ALL untracked content. You can use git clean -Xf -to remove all ignored untracked files, such as build and test byproduct, but leave any -manually created files alone. +to remove all ignored untracked files, such as build and test +byproduct, but leave any manually created files alone. =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. +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. -Suppose that we have a script F<~/testcase.pl> that exits with C<0> when some behaviour is correct, and with C<1> when it's faulty. We need an helper script that automates building C<perl> and running the testcase: +Suppose that we have a script F<~/testcase.pl> that exits with C<0> +when some behaviour is correct, and with C<1> when it's faulty. We need +an helper script that automates building C<perl> and running the +testcase: % cat ~/run #!/bin/sh @@ -379,19 +399,23 @@ Suppose that we have a script F<~/testcase.pl> that exits with C<0> when some be make || exit 125 ./perl -Ilib ~/testcase.pl -This script may return C<125> to indicate that the corresponding commit should be skipped. Otherwise, it returns the status of F<~/testcase.pl>. +This script may return C<125> to indicate that the corresponding commit +should be skipped. Otherwise, it returns the status of +F<~/testcase.pl>. We first enter in bisect mode with: % git bisect start -For example, if the bug is present on C<HEAD> but wasn't in 5.10.0, C<git> will learn about this when you enter: +For example, if the bug is present on C<HEAD> but wasn't in 5.10.0, +C<git> will learn about this when you enter: % git bisect bad % git bisect good perl-5.10.0 Bisecting: 853 revisions left to test after this -This results in checking out the median commit between C<HEAD> and C<perl-5.10.0>. We can then run the bisecting process with: +This results in checking out the median commit between C<HEAD> and +C<perl-5.10.0>. We can then run the bisecting process with: % git bisect run ~/run @@ -407,8 +431,28 @@ When the first bad commit is isolated, C<git bisect> will tell you so: bisect run success -You can peek into the bisecting process with C<git bisect log> and C<git bisect visualize>. C<git bisect reset> will get you out of bisect mode. +You can peek into the bisecting process with C<git bisect log> and +C<git bisect visualize>. C<git bisect reset> will get you out of bisect +mode. + +Please note that the first C<good> state must be an ancestor of the +first C<bad> state. If you want to search for the commit that I<solved> +some bug, you have to negate your test case (i.e. exit with C<1> if OK +and C<0> if not) and still mark the lower bound as C<good> and the +upper as C<bad>. The "first bad commit" has then to be understood as +the "first commit where the bug is solved". + +C<git help bisect> has much more information on how you can tweak your +binary searches. + +=head1 COMITTING TO MAINTENANCE VERSIONS + +To commit to a maintenance version of perl, you need to create a local +tracking branch: + + % git checkout --track -b maint-5.005 origin/maint-5.005 -Please note that the first C<good> state must be an ancestor of the first C<bad> state. If you want to search for the commit that I<solved> some bug, you have to negate your test case (i.e. exit with C<1> if OK and C<0> if not) and still mark the lower bound as C<good> and the upper as C<bad>. The "first bad commit" has then to be understood as the "first commit where the bug is solved". +This creates a local branch named maint-5.005, which tracks the remote +branch origin/maint-5.005. Then you can pull, commit, merge and push as +before. -C<git help bisect> has much more information on how you can tweak your binary searches. |