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. B<NOTE>: that this output is also what you see as a
 170 template if you do not provide a message to c<git commit>.
 171
 172 Assuming we commit all the mentioned changes above:
 173
 174   % git commit -a -m'explain git status and stuff about remotes'
 175   Created commit daf8e63: explain git status and stuff about remotes
 176    1 files changed, 83 insertions(+), 3 deletions(-)
 177
 178 We can re-run git status and see something like this:
 179
 180   % git status
 181   # On branch blead
 182   # Your branch is ahead of 'origin/blead' by 2 commits.
 183   #
 184   # Untracked files:
 185   #   (use "git add <file>..." to include in what will be committed)
 186   #
 187   #       deliberate.untracked
 188   nothing added to commit but untracked files present (use "git add" to track)
 189
 190
 191 When in doubt, before you do anything else, check your status and read it
 192 carefully, many questions are answered directly by the git status output.
 193
 194 =head1 SUBMITTING A PATCH
 195
 196 If you have a patch in mind for Perl, you should first get a copy of
 197 the repository:
 198
 199   % git clone git://perl5.git.perl.org/perl.git perl-git
 200
 201 Then change into the directory:
 202
 203   % cd perl-git
 204
 205 Alternatively, if you already have a Perl repository, you should
 206 ensure that you're on the I<blead> branch, and your repository
 207 is up to date:
 208
 209   % git checkout blead
 210   % git pull
 211
 212 Now that we have everything up to date, we need to create a temporary new
 213 branch for these changes and switch into it:
 214
 215   % git checkout -b orange
 216
 217 which is the short form of
 218
 219   % git branch orange
 220   % git checkout orange
 221
 222 Then make your changes. For example, if Leon Brocard changes his name
 223 to Orange Brocard, we should change his name in the AUTHORS file:
 224
 225   % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
 226
 227 You can see what files are changed:
 228
 229   % git status
 230   # On branch blead
 231   # Changes to be committed:
 232   #   (use "git reset HEAD <file>..." to unstage)
 233   #
 234   #     modified:   AUTHORS
 235   #
 236
 237 And you can see the changes:
 238
 239   % git diff
 240   diff --git a/AUTHORS b/AUTHORS
 241   index 293dd70..722c93e 100644
 242   --- a/AUTHORS
 243   +++ b/AUTHORS
 244   @@ -541,7 +541,7 @@    Lars Hecking                   <lhecking@nmrc.ucc.ie>
 245    Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
 246    Leif Huhn                      <leif@hale.dkstat.com>
 247    Len Johnson                    <lenjay@ibm.net>
 248   -Leon Brocard                   <acme@astray.com>
 249   +Orange Brocard                 <acme@astray.com>
 250    Les Peters                     <lpeters@aol.net>
 251    Lesley Binks                   <lesley.binks@gmail.com>
 252    Lincoln D. Stein               <lstein@cshl.org>
 253
 254 Now commit your change locally:
 255
 256   % git add AUTHORS
 257   % git commit -m 'Rename Leon Brocard to Orange Brocard'
 258   Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
 259    1 files changed, 1 insertions(+), 1 deletions(-)
 260
 261 Now you should create a patch file for all your local changes:
 262
 263   % git format-patch origin
 264   0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
 265
 266 You should now send an email to perl5-porters@perl.org with a
 267 description of your changes, and attach this patch file as an
 268 attachment.
 269
 270 If you want to delete your temporary branch, you may do so with:
 271
 272   % git checkout blead
 273   % git branch -d orange
 274   error: The branch 'orange' is not an ancestor of your current HEAD.
 275   If you are sure you want to delete it, run 'git branch -D orange'.
 276   % git branch -D orange
 277   Deleted branch orange.
 278
 279 =head1 ACCEPTING A PATCH
 280
 281 If you have received a patch file generated using the above section,
 282 you should try out the patch.
 283
 284 First we need to create a temporary new branch for these changes and
 285 switch into it:
 286
 287   % git checkout -b experimental
 288
 289 Now we should apply the patch:
 290
 291   % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
 292   Applying Rename Leon Brocard to Orange Brocard
 293
 294 Now we can inspect the change:
 295
 296   % git log
 297   commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
 298   Author: Leon Brocard <acme@astray.com>
 299   Date:   Fri Dec 19 17:02:59 2008 +0000
 300
 301     Rename Leon Brocard to Orange Brocard
 302   ...
 303
 304   % git diff blead
 305   diff --git a/AUTHORS b/AUTHORS
 306   index 293dd70..722c93e 100644
 307   --- a/AUTHORS
 308   +++ b/AUTHORS
 309   @@ -541,7 +541,7 @@ Lars Hecking                        <lhecking@nmrc.ucc.ie>
 310    Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
 311    Leif Huhn                      <leif@hale.dkstat.com>
 312    Len Johnson                    <lenjay@ibm.net>
 313   -Leon Brocard                   <acme@astray.com>
 314   +Orange Brocard                 <acme@astray.com>
 315    Les Peters                     <lpeters@aol.net>
 316    Lesley Binks                   <lesley.binks@gmail.com>
 317    Lincoln D. Stein               <lstein@cshl.org>
 318
 319 If you are a committer to Perl and you think the patch is good, you can
 320 then merge it into blead then push it out to the main repository:
 321
 322   % git checkout blead
 323   % git pull . experimental
 324   % git push
 325
 326 If you want to delete your temporary branch, you may do so with:
 327
 328   % git checkout blead
 329   % git branch -d experimental
 330   error: The branch 'experimental' is not an ancestor of your current HEAD.
 331   If you are sure you want to delete it, run 'git branch -D experimental'.
 332   % git branch -D experimental
 333   Deleted branch experimental.