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