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 the blead branch (that is, the master branch, which contains bleadperl,
  14 the development version of perl 5) takes up about 160MB of disk space
  15 (including the repository). A build of bleadperl takes up about 200MB
  16 (including the repository and the check out).
  17
  18 =head1 GETTING ACCESS TO THE REPOSITORY
  19
  20 =head2 READ ACCESS VIA THE WEB
  21
  22 You may access this over the web. This allows you to browse the tree,
  23 see recent commits, search for particular commits and more. You may
  24 access it at:
  25
  26   http://perl5.git.perl.org/perl.git
  27
  28 =head2 READ ACCESS VIA GIT
  29
  30 You will need a copy of Git for your computer. You can fetch a copy of
  31 the repository using the Git protocol (which uses port 9418):
  32
  33   git clone git://perl5.git.perl.org/perl.git perl-git
  34
  35 This clones the repository and makes a local copy in the 'perl-git'
  36 directory.
  37
  38 If your local network does not allow you to use port 9418, then you can
  39 fetch a copy of the repository over HTTP (this is slower):
  40
  41   git clone http://perl5.git.perl.org/perl.git perl-http
  42
  43 This clones the repository and makes a local copy in the 'perl-http'
  44 directory.
  45
  46 =head2 WRITE ACCESS TO THE REPOSITORY
  47
  48 If you are a committer, then you can fetch a copy of the repository that
  49 you can push back on with:
  50
  51   git clone ssh://perl5.git.perl.org/gitroot/perl.git perl-ssh
  52
  53 This clones the repository and makes a local copy in the 'perl-ssh'
  54 directory.
  55
  56 If you clone using git, which is faster than ssh, then you will need to
  57 modify your config in order to enable pushing. Edit F<.git/config> where
  58 you will see something like:
  59
  60   [remote "origin"]
  61   url = git://perl5.git.perl.org/perl.git
  62
  63 change that to something like this:
  64
  65   [remote "origin"]
  66   url = ssh://perl5.git.perl.org/gitroot/perl.git
  67
  68 NOTE: there are symlinks set up so that the /gitroot is actually optional.
  69
  70 =head1 OVERVIEW OF THE REPOSITORY
  71
  72 Once you have changed into the repository directory, you can inspect it.
  73
  74
  75 After a clone the repository will contain a single local branch, which
  76 will be the current branch as well, as indicated by the asterix.
  77
  78   % git branch
  79   * blead
  80
  81 Using the -a switch to branch will also show the remote tracking branches in the
  82 repository:
  83
  84   % git branch -a
  85   * blead
  86     origin/HEAD
  87     origin/blead
  88   ...
  89
  90 The branches that begin with "origin" correspond to the "git remote" that
  91 you cloned from (which is named "origin"). Each branch on the remote will
  92 be exactly tracked by theses branches. You should NEVER do work on these
  93 remote tracking branches. You only ever do work in a local branch. Local
  94 branches can be configured to automerge (on pull) from a designated remote
  95 tracking branch. This is the case with the default branch C<blead> which
  96 will be configured to merge from the remote tracking branch
  97 C<origin/blead>.
  98
  99 You can see recent commits:
 100
 101   % git log
 102
 103 And pull new changes from the repository, and update your local repository
 104 (must be clean first)
 105
 106   % git pull
 107
 108 Assuming we are on the branch C<blead> immediately after a pull, this command
 109 would be more or less equivalent to:
 110
 111   % git fetch
 112   % git merge origin/blead
 113
 114 In fact if you want to update your local repository without touching your working
 115 directory you do:
 116
 117   % git fetch
 118
 119 And if you want to update your remote-tracking branches for all defined remotes
 120 simultaneously you can do
 121
 122   % git remote update
 123
 124 Neither of these last two commands will update your working directory, however
 125 both will update the remote-tracking branches in your repository.
 126
 127 To switch to another branch:
 128
 129   % git checkout origin/maint-5.8-dor
 130
 131 To switch back to blead:
 132
 133   % git checkout blead
 134
 135 =head2 FINDING OUT YOUR STATUS
 136
 137 The most common git command you will use will probably be
 138
 139   % git status
 140
 141 This command will produce as output a description of the current state of the
 142 repository, including modified files and unignored untracked files, and in addition
 143 it will show things like what files have been staged for the next commit,
 144 and usually some useful information about how to change things. For instance the
 145 following:
 146
 147   $ git status
 148   # On branch blead
 149   # Your branch is ahead of 'origin/blead' by 1 commit.
 150   #
 151   # Changes to be committed:
 152   #   (use "git reset HEAD <file>..." to unstage)
 153   #
 154   #       modified:   pod/perlrepository.pod
 155   #
 156   # Changed but not updated:
 157   #   (use "git add <file>..." to update what will be committed)
 158   #
 159   #       modified:   pod/perlrepository.pod
 160   #
 161   # Untracked files:
 162   #   (use "git add <file>..." to include in what will be committed)
 163   #
 164   #       deliberate.untracked
 165
 166 This shows that there were changes to this document staged for commit, and
 167 that there were further changes in the working directory not yet staged. It
 168 also shows that there was an untracked file in the working directory, and as
 169 you can see shows how to change all of this. It also shows that there
 170 is one commit on the  working branch C<blead> which has not been pushed to the
 171 C<origin> remote yet. B<NOTE>: that this output is also what you see as a
 172 template if you do not provide a message to C<git commit>.
 173
 174 Assuming we commit all the mentioned changes above:
 175
 176   % git commit -a -m'explain git status and stuff about remotes'
 177   Created commit daf8e63: explain git status and stuff about remotes
 178    1 files changed, 83 insertions(+), 3 deletions(-)
 179
 180 We can re-run git status and see something like this:
 181
 182   % git status
 183   # On branch blead
 184   # Your branch is ahead of 'origin/blead' by 2 commits.
 185   #
 186   # Untracked files:
 187   #   (use "git add <file>..." to include in what will be committed)
 188   #
 189   #       deliberate.untracked
 190   nothing added to commit but untracked files present (use "git add" to track)
 191
 192
 193 When in doubt, before you do anything else, check your status and read it
 194 carefully, many questions are answered directly by the git status output.
 195
 196 =head1 SUBMITTING A PATCH
 197
 198 If you have a patch in mind for Perl, you should first get a copy of
 199 the repository:
 200
 201   % git clone git://perl5.git.perl.org/perl.git perl-git
 202
 203 Then change into the directory:
 204
 205   % cd perl-git
 206
 207 Alternatively, if you already have a Perl repository, you should
 208 ensure that you're on the I<blead> branch, and your repository
 209 is up to date:
 210
 211   % git checkout blead
 212   % git pull
 213
 214 Now that we have everything up to date, we need to create a temporary new
 215 branch for these changes and switch into it:
 216
 217   % git checkout -b orange
 218
 219 which is the short form of
 220
 221   % git branch orange
 222   % git checkout orange
 223
 224 Then make your changes. For example, if Leon Brocard changes his name
 225 to Orange Brocard, we should change his name in the AUTHORS file:
 226
 227   % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
 228
 229 You can see what files are changed:
 230
 231   % git status
 232   # On branch blead
 233   # Changes to be committed:
 234   #   (use "git reset HEAD <file>..." to unstage)
 235   #
 236   #     modified:   AUTHORS
 237   #
 238
 239 And you can see the changes:
 240
 241   % git diff
 242   diff --git a/AUTHORS b/AUTHORS
 243   index 293dd70..722c93e 100644
 244   --- a/AUTHORS
 245   +++ b/AUTHORS
 246   @@ -541,7 +541,7 @@    Lars Hecking                   <lhecking@nmrc.ucc.ie>
 247    Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
 248    Leif Huhn                      <leif@hale.dkstat.com>
 249    Len Johnson                    <lenjay@ibm.net>
 250   -Leon Brocard                   <acme@astray.com>
 251   +Orange Brocard                 <acme@astray.com>
 252    Les Peters                     <lpeters@aol.net>
 253    Lesley Binks                   <lesley.binks@gmail.com>
 254    Lincoln D. Stein               <lstein@cshl.org>
 255
 256 Now commit your change locally:
 257
 258   % git add AUTHORS
 259   % git commit -m 'Rename Leon Brocard to Orange Brocard'
 260   Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
 261    1 files changed, 1 insertions(+), 1 deletions(-)
 262
 263 Now you should create a patch file for all your local changes:
 264
 265   % git format-patch origin
 266   0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
 267
 268 You should now send an email to perl5-porters@perl.org with a
 269 description of your changes, and attach this patch file as an
 270 attachment.
 271
 272 If you want to delete your temporary branch, you may do so with:
 273
 274   % git checkout blead
 275   % git branch -d orange
 276   error: The branch 'orange' is not an ancestor of your current HEAD.
 277   If you are sure you want to delete it, run 'git branch -D orange'.
 278   % git branch -D orange
 279   Deleted branch orange.
 280
 281 =head1 ACCEPTING A PATCH
 282
 283 If you have received a patch file generated using the above section,
 284 you should try out the patch.
 285
 286 First we need to create a temporary new branch for these changes and
 287 switch into it:
 288
 289   % git checkout -b experimental
 290
 291 Now we should apply the patch:
 292
 293   % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
 294   Applying Rename Leon Brocard to Orange Brocard
 295
 296 Now we can inspect the change:
 297
 298   % git log
 299   commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
 300   Author: Leon Brocard <acme@astray.com>
 301   Date:   Fri Dec 19 17:02:59 2008 +0000
 302
 303     Rename Leon Brocard to Orange Brocard
 304   ...
 305
 306   % git diff blead
 307   diff --git a/AUTHORS b/AUTHORS
 308   index 293dd70..722c93e 100644
 309   --- a/AUTHORS
 310   +++ b/AUTHORS
 311   @@ -541,7 +541,7 @@ Lars Hecking                        <lhecking@nmrc.ucc.ie>
 312    Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
 313    Leif Huhn                      <leif@hale.dkstat.com>
 314    Len Johnson                    <lenjay@ibm.net>
 315   -Leon Brocard                   <acme@astray.com>
 316   +Orange Brocard                 <acme@astray.com>
 317    Les Peters                     <lpeters@aol.net>
 318    Lesley Binks                   <lesley.binks@gmail.com>
 319    Lincoln D. Stein               <lstein@cshl.org>
 320
 321 If you are a committer to Perl and you think the patch is good, you can
 322 then merge it into blead then push it out to the main repository:
 323
 324   % git checkout blead
 325   % git merge experimental
 326   % git push
 327
 328 If you want to delete your temporary branch, you may do so with:
 329
 330   % git checkout blead
 331   % git branch -d experimental
 332   error: The branch 'experimental' is not an ancestor of your current HEAD.
 333   If you are sure you want to delete it, run 'git branch -D experimental'.
 334   % git branch -D experimental
 335   Deleted branch experimental.