pod/perlrepository.pod

   1 =head1 NAME
   2
   3 perlrepository - Using the Perl source repository
   4
   5 =head1 SYNOPSIS
   6
   7 All of Perl's source code is kept centrally in a Git repository. The
   8 repository contains many Perl revisions from Perl 1 onwards and all
   9 the revisions from Perforce, the version control system we were using
  10 previously. This repository is accessible in different ways.
  11
  12 The full repository takes up about 80MB of disk space. A check out of
  13 blead takes up about 160MB of disk space (including the repository). A
  14 build of blead takes up about 200MB (including the repository and the
  15 check out).
  16
  17 =head1 GETTING ACCESS TO THE REPOSITORY
  18
  19 =head2 READ ACCESS VIA THE WEB
  20
  21 You may access this over the web. This allows you to browse the tree,
  22 see recent commits, search for particular commits and more. You may
  23 access it at:
  24
  25   http://perl5.git.perl.org/perl.git
  26
  27 =head2 READ ACCESS VIA GIT
  28
  29 You will need a copy of Git for your computer. You can fetch a copy of
  30 the repository using the Git protocol (which uses port 9418):
  31
  32   git clone git://perl5.git.perl.org/perl.git perl-git
  33
  34 This clones the repository and makes a local copy in the 'perl-git'
  35 directory.
  36
  37 If your local network does not allow you to use port 9418, then you can
  38 fetch a copy of the repository over HTTP (this is slower):
  39
  40   git clone http://perl5.git.perl.org/perl.git perl-http
  41
  42 This clones the repository and makes a local copy in the 'perl-http'
  43 directory.
  44
  45 =head2 WRITE ACCESS TO THE REPOSITORY
  46
  47 If you are a committer, then you can fetch a copy of the repository that
  48 you can push back on with:
  49
  50   git clone ssh://perl5.git.perl.org/gitroot/perl.git perl-ssh
  51
  52 This clones the repository and makes a local copy in the 'perl-ssh'
  53 directory.
  54
  55 If you clone using git, which is faster than ssh, then you will need to
  56 modify your config in order to enable pushing. Edit .git/config where
  57 you will see something like:
  58
  59   [remote "origin"]
  60   url = git://perl5.git.perl.org/perl.git
  61
  62 change that to something like this:
  63
  64   [remote "origin"]
  65   url = ssh://perl5.git.perl.org/gitroot/perl.git
  66
  67 NOTE: there are symlinks set up so that the /gitroot is actually optional.
  68
  69 =head1 OVERVIEW OF THE REPOSITORY
  70
  71 Once you have changed into the repository directory, you can inspect it.
  72
  73 The repository contains a few branches:
  74
  75   % git branch -a
  76   * blead
  77     origin/HEAD
  78     origin/blead
  79   ...
  80
  81 You can see recent commits:
  82
  83   % git log
  84
  85 And pull new changes from the repository:
  86
  87   % git pull
  88
  89 To switch to another branch:
  90
  91   % git checkout origin/maint-5.8-dor
  92
  93 To switch back to blead:
  94
  95   % git checkout blead
  96
  97 =head1 SUBMITTING A PATCH
  98
  99 If you have a patch in mind for Perl, you should first get a copy of
 100 the repository:
 101
 102   % git clone git://perl5.git.perl.org/perl.git perl-git
 103
 104 Then change into the directory:
 105
 106   % cd perl-git
 107
 108 Alternatively, if you already have a Perl repository, you should
 109 ensure that you're on the I<blead> branch, and your repository
 110 is up to date:
 111
 112   % git checkout blead
 113   % git pull
 114
 115 Now that we have everything up to date, we need to create a temporary new
 116 branch for these changes and switch into it:
 117
 118   % git checkout -b orange
 119
 120 which is the short form of
 121
 122   % git branch orange
 123   % git checkout orange
 124
 125 Then make your changes. For example, if Leon Brocard changes his name
 126 to Orange Brocard, we should change his name in the AUTHORS file:
 127
 128   % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
 129
 130 You can see what files are changed:
 131
 132   % git status
 133   # On branch blead
 134   # Changes to be committed:
 135   #   (use "git reset HEAD <file>..." to unstage)
 136   #
 137   #     modified:   AUTHORS
 138   #
 139
 140 And you can see the changes:
 141
 142   % git diff
 143   diff --git a/AUTHORS b/AUTHORS
 144   index 293dd70..722c93e 100644
 145   --- a/AUTHORS
 146   +++ b/AUTHORS
 147   @@ -541,7 +541,7 @@    Lars Hecking                   <lhecking@nmrc.ucc.ie>
 148    Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
 149    Leif Huhn                      <leif@hale.dkstat.com>
 150    Len Johnson                    <lenjay@ibm.net>
 151   -Leon Brocard                   <acme@astray.com>
 152   +Orange Brocard                 <acme@astray.com>
 153    Les Peters                     <lpeters@aol.net>
 154    Lesley Binks                   <lesley.binks@gmail.com>
 155    Lincoln D. Stein               <lstein@cshl.org>
 156
 157 Now commit your change locally:
 158
 159   % git add AUTHORS
 160   % git commit -m 'Rename Leon Brocard to Orange Brocard'
 161   Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
 162    1 files changed, 1 insertions(+), 1 deletions(-)
 163
 164 Now you should create a patch file for all your local changes:
 165
 166   % git format-patch origin
 167   0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
 168
 169 You should now send an email to perl5-porters@perl.org with a
 170 description of your changes, and attach this patch file as an
 171 attachment.
 172
 173 If you want to delete your temporary branch, you may do so with:
 174
 175   % git checkout blead
 176   % git branch -d orange
 177   error: The branch 'orange' is not an ancestor of your current HEAD.
 178   If you are sure you want to delete it, run 'git branch -D orange'.
 179   % git branch -D orange
 180   Deleted branch orange.
 181
 182 =head1 ACCEPTING A PATCH
 183
 184 If you have received a patch file generated using the above section,
 185 you should try out the patch.
 186
 187 First we need to create a temporary new branch for these changes and
 188 switch into it:
 189
 190   % git checkout -b experimental
 191
 192 Now we should apply the patch:
 193
 194   % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
 195   Applying Rename Leon Brocard to Orange Brocard
 196
 197 Now we can inspect the change:
 198
 199   % git log
 200   commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
 201   Author: Leon Brocard <acme@astray.com>
 202   Date:   Fri Dec 19 17:02:59 2008 +0000
 203
 204     Rename Leon Brocard to Orange Brocard
 205   ...
 206
 207   % git diff blead
 208   diff --git a/AUTHORS b/AUTHORS
 209   index 293dd70..722c93e 100644
 210   --- a/AUTHORS
 211   +++ b/AUTHORS
 212   @@ -541,7 +541,7 @@ Lars Hecking                        <lhecking@nmrc.ucc.ie>
 213    Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
 214    Leif Huhn                      <leif@hale.dkstat.com>
 215    Len Johnson                    <lenjay@ibm.net>
 216   -Leon Brocard                   <acme@astray.com>
 217   +Orange Brocard                 <acme@astray.com>
 218    Les Peters                     <lpeters@aol.net>
 219    Lesley Binks                   <lesley.binks@gmail.com>
 220    Lincoln D. Stein               <lstein@cshl.org>
 221
 222 If you are a committer to Perl and you think the patch is good, you can
 223 then merge it into blead then push it out to the main repository:
 224
 225   % git checkout blead
 226   % git pull . experimental
 227   % git push
 228
 229 If you want to delete your temporary branch, you may do so with:
 230
 231   % git checkout blead
 232   % git branch -d experimental
 233   error: The branch 'experimental' is not an ancestor of your current HEAD.
 234   If you are sure you want to delete it, run 'git branch -D experimental'.
 235   % git branch -D experimental
 236   Deleted branch experimental.