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
  74 After a clone the repository will contain a single local branch, which
  75 will be the current branch as well, as indicated by the asterix.
  76
  77   % git branch
  78   * blead
  79
  80 Using the -a switch to branch will show the remote tracking branches in the
  81 repository:
  82
  83   % git branch -r
  84   * blead
  85     origin/HEAD
  86     origin/blead
  87   ...
  88
  89 The branches that begin with "origin" correspond to the "git remote" that
  90 you cloned from. Each branch on the remote will be exactly tracked by theses
  91 branches. You should NEVER do work on these remote tracking branches. You only
  92 ever do work in a local branch. Local branches can be configured to automerge
  93 (on pull) from a designated remote tracking branch. This is the case with the
  94 default branch C<blead> which will be configured to merge from the remote
  95 tracking branch C<origin/blead>.
  96
  97 You can see recent commits:
  98
  99   % git log
 100
 101 And pull new changes from the repository, and update your local repository
 102 (must be clean first)
 103
 104   % git pull
 105
 106 Assuming we are on the branch C<blead> immediately after a pull, this command
 107 would be more or less equivalent to:
 108
 109   % git fetch
 110   % git merge origin/blead
 111
 112 In fact if you want to update your local repository without touching your working
 113 directory you do:
 114
 115   % git fetch
 116
 117 And if you want to update your remote tracking branches for all defined remotes
 118 simultaneously you do
 119
 120   % git remote update
 121
 122 Neither of these last two commands will update your working directory, however
 123 both will update the repository.
 124
 125 To switch to another branch:
 126
 127   % git checkout origin/maint-5.8-dor
 128
 129 To switch back to blead:
 130
 131   % git checkout blead
 132
 133 =head2 FINDING OUT YOUR STATUS
 134
 135 The most common git command you will use will probably be
 136
 137   % git status
 138
 139 This command will produce as output a description of the current state of the
 140 repository, including modified files and unignored untracked files, and in addition
 141 it will show things like what files have been staged for the next commit,
 142 and usually some useful information about how to change things. For instance the
 143 following:
 144
 145   $ git status
 146   # On branch blead
 147   # Your branch is ahead of 'origin/blead' by 1 commit.
 148   #
 149   # Changes to be committed:
 150   #   (use "git reset HEAD <file>..." to unstage)
 151   #
 152   #       modified:   pod/perlrepository.pod
 153   #
 154   # Changed but not updated:
 155   #   (use "git add <file>..." to update what will be committed)
 156   #
 157   #       modified:   pod/perlrepository.pod
 158   #
 159   # Untracked files:
 160   #   (use "git add <file>..." to include in what will be committed)
 161   #
 162   #       deliberate.untracked
 163
 164 This shows that there were changes to this document staged for commit, and
 165 that there were further changes in the working directory not yet staged. It
 166 also shows that there was an untracked file in the working directory, and as
 167 you can see shows how to change all of this. It also shows that there
 168 is one commit on the  working branch C<blead> which has not been pushed to the
 169 C<origin> remote yet.
 170
 171 When in doubt, before you do anything else, check your status and read it
 172 carefully, many questions are answered directly by the git status output.
 173
 174 NOTE: that this output is also what you see as a template if you do not
 175 provide a message to c<git commit>.
 176
 177 =head1 SUBMITTING A PATCH
 178
 179 If you have a patch in mind for Perl, you should first get a copy of
 180 the repository:
 181
 182   % git clone git://perl5.git.perl.org/perl.git perl-git
 183
 184 Then change into the directory:
 185
 186   % cd perl-git
 187
 188 Alternatively, if you already have a Perl repository, you should
 189 ensure that you're on the I<blead> branch, and your repository
 190 is up to date:
 191
 192   % git checkout blead
 193   % git pull
 194
 195 Now that we have everything up to date, we need to create a temporary new
 196 branch for these changes and switch into it:
 197
 198   % git checkout -b orange
 199
 200 which is the short form of
 201
 202   % git branch orange
 203   % git checkout orange
 204
 205 Then make your changes. For example, if Leon Brocard changes his name
 206 to Orange Brocard, we should change his name in the AUTHORS file:
 207
 208   % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
 209
 210 You can see what files are changed:
 211
 212   % git status
 213   # On branch blead
 214   # Changes to be committed:
 215   #   (use "git reset HEAD <file>..." to unstage)
 216   #
 217   #     modified:   AUTHORS
 218   #
 219
 220 And you can see the changes:
 221
 222   % git diff
 223   diff --git a/AUTHORS b/AUTHORS
 224   index 293dd70..722c93e 100644
 225   --- a/AUTHORS
 226   +++ b/AUTHORS
 227   @@ -541,7 +541,7 @@    Lars Hecking                   <lhecking@nmrc.ucc.ie>
 228    Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
 229    Leif Huhn                      <leif@hale.dkstat.com>
 230    Len Johnson                    <lenjay@ibm.net>
 231   -Leon Brocard                   <acme@astray.com>
 232   +Orange Brocard                 <acme@astray.com>
 233    Les Peters                     <lpeters@aol.net>
 234    Lesley Binks                   <lesley.binks@gmail.com>
 235    Lincoln D. Stein               <lstein@cshl.org>
 236
 237 Now commit your change locally:
 238
 239   % git add AUTHORS
 240   % git commit -m 'Rename Leon Brocard to Orange Brocard'
 241   Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
 242    1 files changed, 1 insertions(+), 1 deletions(-)
 243
 244 Now you should create a patch file for all your local changes:
 245
 246   % git format-patch origin
 247   0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
 248
 249 You should now send an email to perl5-porters@perl.org with a
 250 description of your changes, and attach this patch file as an
 251 attachment.
 252
 253 If you want to delete your temporary branch, you may do so with:
 254
 255   % git checkout blead
 256   % git branch -d orange
 257   error: The branch 'orange' is not an ancestor of your current HEAD.
 258   If you are sure you want to delete it, run 'git branch -D orange'.
 259   % git branch -D orange
 260   Deleted branch orange.
 261
 262 =head1 ACCEPTING A PATCH
 263
 264 If you have received a patch file generated using the above section,
 265 you should try out the patch.
 266
 267 First we need to create a temporary new branch for these changes and
 268 switch into it:
 269
 270   % git checkout -b experimental
 271
 272 Now we should apply the patch:
 273
 274   % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
 275   Applying Rename Leon Brocard to Orange Brocard
 276
 277 Now we can inspect the change:
 278
 279   % git log
 280   commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
 281   Author: Leon Brocard <acme@astray.com>
 282   Date:   Fri Dec 19 17:02:59 2008 +0000
 283
 284     Rename Leon Brocard to Orange Brocard
 285   ...
 286
 287   % git diff blead
 288   diff --git a/AUTHORS b/AUTHORS
 289   index 293dd70..722c93e 100644
 290   --- a/AUTHORS
 291   +++ b/AUTHORS
 292   @@ -541,7 +541,7 @@ Lars Hecking                        <lhecking@nmrc.ucc.ie>
 293    Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
 294    Leif Huhn                      <leif@hale.dkstat.com>
 295    Len Johnson                    <lenjay@ibm.net>
 296   -Leon Brocard                   <acme@astray.com>
 297   +Orange Brocard                 <acme@astray.com>
 298    Les Peters                     <lpeters@aol.net>
 299    Lesley Binks                   <lesley.binks@gmail.com>
 300    Lincoln D. Stein               <lstein@cshl.org>
 301
 302 If you are a committer to Perl and you think the patch is good, you can
 303 then merge it into blead then push it out to the main repository:
 304
 305   % git checkout blead
 306   % git pull . experimental
 307   % git push
 308
 309 If you want to delete your temporary branch, you may do so with:
 310
 311   % git checkout blead
 312   % git branch -d experimental
 313   error: The branch 'experimental' is not an ancestor of your current HEAD.
 314   If you are sure you want to delete it, run 'git branch -D experimental'.
 315   % git branch -D experimental
 316   Deleted branch experimental.