This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
autodie information added to Maintainers.pl
[perl5.git] / pod / perlrepository.pod
CommitLineData
d7dd28b6
LB
1=head1 NAME
2
3perlrepository - Using the Perl source repository
4
5=head1 SYNOPSIS
6
7All of Perl's source code is kept centrally in a Git repository. The
6acba58e
LB
8repository contains many Perl revisions from Perl 1 onwards and all the
9revisions from Perforce, the version control system we were using
d7dd28b6
LB
10previously. This repository is accessible in different ways.
11
12The full repository takes up about 80MB of disk space. A check out of
d9847473
RGS
13the blead branch (that is, the master branch, which contains bleadperl,
14the 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).
d7dd28b6
LB
17
18=head1 GETTING ACCESS TO THE REPOSITORY
19
20=head2 READ ACCESS VIA THE WEB
21
22You may access this over the web. This allows you to browse the tree,
23see recent commits, search for particular commits and more. You may
24access it at:
25
26 http://perl5.git.perl.org/perl.git
27
28=head2 READ ACCESS VIA GIT
29
30You will need a copy of Git for your computer. You can fetch a copy of
31the repository using the Git protocol (which uses port 9418):
32
3b8a5fb0 33 git clone git://perl5.git.perl.org/perl.git perl-git
d7dd28b6 34
3b8a5fb0 35This clones the repository and makes a local copy in the 'perl-git'
d7dd28b6
LB
36directory.
37
38If your local network does not allow you to use port 9418, then you can
572f57ba 39fetch a copy of the repository over HTTP (this is slower):
d7dd28b6 40
3b8a5fb0 41 git clone http://perl5.git.perl.org/perl.git perl-http
d7dd28b6 42
3b8a5fb0 43This clones the repository and makes a local copy in the 'perl-http'
d7dd28b6
LB
44directory.
45
46=head2 WRITE ACCESS TO THE REPOSITORY
47
6acba58e
LB
48If you are a committer, then you can fetch a copy of the repository
49that you can push back on with:
d7dd28b6 50
3b8a5fb0 51 git clone ssh://perl5.git.perl.org/gitroot/perl.git perl-ssh
d7dd28b6 52
3b8a5fb0 53This clones the repository and makes a local copy in the 'perl-ssh'
d7dd28b6
LB
54directory.
55
1a0f15d5 56If you clone using git, which is faster than ssh, then you will need to
6acba58e
LB
57modify your config in order to enable pushing. Edit F<.git/config>
58where you will see something like:
1a0f15d5
YO
59
60 [remote "origin"]
61 url = git://perl5.git.perl.org/perl.git
62
63change that to something like this:
64
65 [remote "origin"]
66 url = ssh://perl5.git.perl.org/gitroot/perl.git
67
6acba58e
LB
68NOTE: there are symlinks set up so that the /gitroot is actually
69optional.
d7dd28b6 70
184487f0
NC
71You can also set up your user name and e-mail address. For example
72
73 % git config user.name "Leon Brocard"
74 % git config user.email acme@astray.com
75
6acba58e
LB
76It is also possible to keep C<origin> as a git remote, and add a new
77remote for ssh access:
f6c12373
VP
78
79 % git remote add camel user@camel:/gitroot/perl.git
80
6acba58e
LB
81This allows you to update your local repository by pulling from
82C<origin>, which is faster and doesn't require you to authentify, and
83to push your changes back with the C<camel> remote:
f6c12373
VP
84
85 % git fetch camel
86 % git push camel
87
6acba58e
LB
88The C<fetch> command just updates the C<camel> refs, as the objects
89themselves should have been fetched when pulling from C<origin>.
f6c12373 90
d7dd28b6
LB
91=head1 OVERVIEW OF THE REPOSITORY
92
6acba58e
LB
93Once you have changed into the repository directory, you can inspect
94it.
d7dd28b6 95
d7dd28b6 96
39219fd3
YO
97After a clone the repository will contain a single local branch, which
98will be the current branch as well, as indicated by the asterix.
99
100 % git branch
101 * blead
102
6acba58e
LB
103Using the -a switch to branch will also show the remote tracking
104branches in the repository:
39219fd3 105
d9847473 106 % git branch -a
09081495 107 * blead
d7dd28b6
LB
108 origin/HEAD
109 origin/blead
110 ...
111
6acba58e
LB
112The branches that begin with "origin" correspond to the "git remote"
113that you cloned from (which is named "origin"). Each branch on the
114remote will be exactly tracked by theses branches. You should NEVER do
115work on these remote tracking branches. You only ever do work in a
116local branch. Local branches can be configured to automerge (on pull)
117from a designated remote tracking branch. This is the case with the
118default branch C<blead> which will be configured to merge from the
119remote tracking branch C<origin/blead>.
39219fd3 120
d7dd28b6
LB
121You can see recent commits:
122
c2cf2042 123 % git log
d7dd28b6 124
6acba58e
LB
125And pull new changes from the repository, and update your local
126repository (must be clean first)
d7dd28b6
LB
127
128 % git pull
09081495 129
6acba58e
LB
130Assuming we are on the branch C<blead> immediately after a pull, this
131command would be more or less equivalent to:
39219fd3
YO
132
133 % git fetch
134 % git merge origin/blead
135
6acba58e
LB
136In fact if you want to update your local repository without touching
137your working directory you do:
39219fd3
YO
138
139 % git fetch
140
6acba58e
LB
141And if you want to update your remote-tracking branches for all defined
142remotes simultaneously you can do
39219fd3
YO
143
144 % git remote update
145
6acba58e
LB
146Neither of these last two commands will update your working directory,
147however both will update the remote-tracking branches in your
148repository.
39219fd3 149
09081495
LB
150To switch to another branch:
151
152 % git checkout origin/maint-5.8-dor
153
154To switch back to blead:
155
156 % git checkout blead
c2cf2042 157
39219fd3
YO
158=head2 FINDING OUT YOUR STATUS
159
160The most common git command you will use will probably be
161
162 % git status
163
6acba58e
LB
164This command will produce as output a description of the current state
165of the repository, including modified files and unignored untracked
166files, and in addition it will show things like what files have been
167staged for the next commit, and usually some useful information about
168how to change things. For instance the following:
39219fd3
YO
169
170 $ git status
171 # On branch blead
172 # Your branch is ahead of 'origin/blead' by 1 commit.
173 #
174 # Changes to be committed:
175 # (use "git reset HEAD <file>..." to unstage)
176 #
177 # modified: pod/perlrepository.pod
178 #
179 # Changed but not updated:
180 # (use "git add <file>..." to update what will be committed)
181 #
182 # modified: pod/perlrepository.pod
183 #
184 # Untracked files:
185 # (use "git add <file>..." to include in what will be committed)
186 #
187 # deliberate.untracked
188
6acba58e
LB
189This shows that there were changes to this document staged for commit,
190and that there were further changes in the working directory not yet
191staged. It also shows that there was an untracked file in the working
192directory, and as you can see shows how to change all of this. It also
193shows that there is one commit on the working branch C<blead> which
194has not been pushed to the C<origin> remote yet. B<NOTE>: that this
195output is also what you see as a template if you do not provide a
196message to C<git commit>.
7f6effc7
YO
197
198Assuming we commit all the mentioned changes above:
199
200 % git commit -a -m'explain git status and stuff about remotes'
201 Created commit daf8e63: explain git status and stuff about remotes
202 1 files changed, 83 insertions(+), 3 deletions(-)
203
204We can re-run git status and see something like this:
205
206 % git status
207 # On branch blead
208 # Your branch is ahead of 'origin/blead' by 2 commits.
209 #
210 # Untracked files:
211 # (use "git add <file>..." to include in what will be committed)
212 #
213 # deliberate.untracked
214 nothing added to commit but untracked files present (use "git add" to track)
215
39219fd3 216
6acba58e
LB
217When in doubt, before you do anything else, check your status and read
218it carefully, many questions are answered directly by the git status
219output.
39219fd3 220
c2cf2042
LB
221=head1 SUBMITTING A PATCH
222
223If you have a patch in mind for Perl, you should first get a copy of
224the repository:
225
226 % git clone git://perl5.git.perl.org/perl.git perl-git
227
228Then change into the directory:
229
230 % cd perl-git
231
6acba58e
LB
232Alternatively, if you already have a Perl repository, you should ensure
233that you're on the I<blead> branch, and your repository is up to date:
12322d22
A
234
235 % git checkout blead
236 % git pull
237
6acba58e
LB
238Now that we have everything up to date, we need to create a temporary
239new branch for these changes and switch into it:
b1fccde5 240
a9b05323 241 % git checkout -b orange
23f8d33e 242
a9b05323
YO
243which is the short form of
244
b1fccde5
LB
245 % git branch orange
246 % git checkout orange
247
c2cf2042
LB
248Then make your changes. For example, if Leon Brocard changes his name
249to Orange Brocard, we should change his name in the AUTHORS file:
250
251 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
252
253You can see what files are changed:
254
255 % git status
256 # On branch blead
257 # Changes to be committed:
258 # (use "git reset HEAD <file>..." to unstage)
259 #
260 # modified: AUTHORS
261 #
262
c2cf2042
LB
263And you can see the changes:
264
265 % git diff
266 diff --git a/AUTHORS b/AUTHORS
267 index 293dd70..722c93e 100644
268 --- a/AUTHORS
269 +++ b/AUTHORS
7df2e4bc 270 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
c2cf2042
LB
271 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
272 Leif Huhn <leif@hale.dkstat.com>
273 Len Johnson <lenjay@ibm.net>
274 -Leon Brocard <acme@astray.com>
275 +Orange Brocard <acme@astray.com>
276 Les Peters <lpeters@aol.net>
277 Lesley Binks <lesley.binks@gmail.com>
278 Lincoln D. Stein <lstein@cshl.org>
279
280Now commit your change locally:
281
282 % git add AUTHORS
283 % git commit -m 'Rename Leon Brocard to Orange Brocard'
284 Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
285 1 files changed, 1 insertions(+), 1 deletions(-)
286
287Now you should create a patch file for all your local changes:
288
2af192ee 289 % git format-patch origin
c2cf2042
LB
290 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
291
292You should now send an email to perl5-porters@perl.org with a
293description of your changes, and attach this patch file as an
294attachment.
295
b1fccde5
LB
296If you want to delete your temporary branch, you may do so with:
297
298 % git checkout blead
299 % git branch -d orange
300 error: The branch 'orange' is not an ancestor of your current HEAD.
301 If you are sure you want to delete it, run 'git branch -D orange'.
302 % git branch -D orange
303 Deleted branch orange.
7df2e4bc
LB
304
305=head1 ACCEPTING A PATCH
306
307If you have received a patch file generated using the above section,
308you should try out the patch.
309
310First we need to create a temporary new branch for these changes and
311switch into it:
312
a9b05323 313 % git checkout -b experimental
7df2e4bc 314
6acba58e
LB
315Patches that were formatted by C<git format-patch> are applied with
316C<git am>:
7df2e4bc 317
2af192ee 318 % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
7df2e4bc
LB
319 Applying Rename Leon Brocard to Orange Brocard
320
6acba58e
LB
321If just a raw diff is provided, it is also possible use this two-step
322process:
09645c26
VP
323
324 % git apply bugfix.diff
325 % git commit -am "Some fixing" --author="That Guy <that.guy@internets.com>"
326
7df2e4bc
LB
327Now we can inspect the change:
328
329 % git log
330 commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
331 Author: Leon Brocard <acme@astray.com>
332 Date: Fri Dec 19 17:02:59 2008 +0000
333
334 Rename Leon Brocard to Orange Brocard
335 ...
336
337 % git diff blead
338 diff --git a/AUTHORS b/AUTHORS
339 index 293dd70..722c93e 100644
340 --- a/AUTHORS
341 +++ b/AUTHORS
342 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
343 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
344 Leif Huhn <leif@hale.dkstat.com>
345 Len Johnson <lenjay@ibm.net>
346 -Leon Brocard <acme@astray.com>
347 +Orange Brocard <acme@astray.com>
348 Les Peters <lpeters@aol.net>
349 Lesley Binks <lesley.binks@gmail.com>
350 Lincoln D. Stein <lstein@cshl.org>
351
352If you are a committer to Perl and you think the patch is good, you can
75fb7651 353then merge it into blead then push it out to the main repository:
7df2e4bc
LB
354
355 % git checkout blead
d9847473 356 % git merge experimental
75fb7651 357 % git push
7df2e4bc
LB
358
359If you want to delete your temporary branch, you may do so with:
360
361 % git checkout blead
362 % git branch -d experimental
363 error: The branch 'experimental' is not an ancestor of your current HEAD.
364 If you are sure you want to delete it, run 'git branch -D experimental'.
365 % git branch -D experimental
366 Deleted branch experimental.
b0d36535
YO
367
368=head1 CLEANING A WORKING DIRECTORY
369
6acba58e
LB
370The command C<git clean> can with varying arguments be used as a
371replacement for make-clean.
b0d36535
YO
372
373To reset your working directory to a pristine condition you can do:
374
375 git clean -dxf
376
377However, be aware this will delete ALL untracked content. You can use
378
379 git clean -Xf
380
6acba58e
LB
381to remove all ignored untracked files, such as build and test
382byproduct, but leave any manually created files alone.
b0d36535 383
d82a90c1
VP
384=head1 BISECTING
385
6acba58e
LB
386C<git> provides a built-in way to determine, with a binary search in
387the history, which commit should be blamed for introducing a given bug.
d82a90c1 388
6acba58e
LB
389Suppose that we have a script F<~/testcase.pl> that exits with C<0>
390when some behaviour is correct, and with C<1> when it's faulty. We need
391an helper script that automates building C<perl> and running the
392testcase:
d82a90c1
VP
393
394 % cat ~/run
395 #!/bin/sh
396 git clean -dxf
397 # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
398 sh Configure -des -Dusedevel -Doptimize="-g" || exit 125
399 make || exit 125
400 ./perl -Ilib ~/testcase.pl
401
6acba58e
LB
402This script may return C<125> to indicate that the corresponding commit
403should be skipped. Otherwise, it returns the status of
404F<~/testcase.pl>.
d82a90c1
VP
405
406We first enter in bisect mode with:
407
408 % git bisect start
409
6acba58e
LB
410For example, if the bug is present on C<HEAD> but wasn't in 5.10.0,
411C<git> will learn about this when you enter:
d82a90c1
VP
412
413 % git bisect bad
414 % git bisect good perl-5.10.0
415 Bisecting: 853 revisions left to test after this
416
6acba58e
LB
417This results in checking out the median commit between C<HEAD> and
418C<perl-5.10.0>. We can then run the bisecting process with:
d82a90c1
VP
419
420 % git bisect run ~/run
421
422When the first bad commit is isolated, C<git bisect> will tell you so:
423
424 ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
425 commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
426 Author: Dave Mitchell <davem@fdisolutions.com>
427 Date: Sat Feb 9 14:56:23 2008 +0000
428
429 [perl #49472] Attributes + Unkown Error
430 ...
431
432 bisect run success
433
6acba58e
LB
434You can peek into the bisecting process with C<git bisect log> and
435C<git bisect visualize>. C<git bisect reset> will get you out of bisect
436mode.
d82a90c1 437
6acba58e
LB
438Please note that the first C<good> state must be an ancestor of the
439first C<bad> state. If you want to search for the commit that I<solved>
440some bug, you have to negate your test case (i.e. exit with C<1> if OK
441and C<0> if not) and still mark the lower bound as C<good> and the
442upper as C<bad>. The "first bad commit" has then to be understood as
443the "first commit where the bug is solved".
d82a90c1 444
6acba58e
LB
445C<git help bisect> has much more information on how you can tweak your
446binary searches.
9d68b7ed
LB
447
448=head1 COMITTING TO MAINTENANCE VERSIONS
449
450To commit to a maintenance version of perl, you need to create a local
451tracking branch:
452
453 % git checkout --track -b maint-5.005 origin/maint-5.005
454
455This creates a local branch named maint-5.005, which tracks the remote
6acba58e
LB
456branch origin/maint-5.005. Then you can pull, commit, merge and push as
457before.
458