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