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 | |
f755e97d |
35 | This clones the repository and makes a local copy in the F<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 | |
f755e97d |
43 | This clones the repository and makes a local copy in the F<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 |
f755e97d |
82 | C<origin>, which is faster and doesn't require you to authenticate, and |
6acba58e |
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 | |
39219fd3 |
96 | After a clone the repository will contain a single local branch, which |
97 | will be the current branch as well, as indicated by the asterix. |
98 | |
99 | % git branch |
100 | * blead |
101 | |
f755e97d |
102 | Using the -a switch to C<branch> will also show the remote tracking |
6acba58e |
103 | branches in the repository: |
39219fd3 |
104 | |
d9847473 |
105 | % git branch -a |
09081495 |
106 | * blead |
d7dd28b6 |
107 | origin/HEAD |
108 | origin/blead |
109 | ... |
110 | |
6acba58e |
111 | The branches that begin with "origin" correspond to the "git remote" |
112 | that you cloned from (which is named "origin"). Each branch on the |
113 | remote will be exactly tracked by theses branches. You should NEVER do |
114 | work on these remote tracking branches. You only ever do work in a |
115 | local branch. Local branches can be configured to automerge (on pull) |
116 | from a designated remote tracking branch. This is the case with the |
117 | default branch C<blead> which will be configured to merge from the |
118 | remote tracking branch C<origin/blead>. |
39219fd3 |
119 | |
d7dd28b6 |
120 | You can see recent commits: |
121 | |
c2cf2042 |
122 | % git log |
d7dd28b6 |
123 | |
6acba58e |
124 | And pull new changes from the repository, and update your local |
125 | repository (must be clean first) |
d7dd28b6 |
126 | |
127 | % git pull |
09081495 |
128 | |
6acba58e |
129 | Assuming we are on the branch C<blead> immediately after a pull, this |
130 | command would be more or less equivalent to: |
39219fd3 |
131 | |
132 | % git fetch |
133 | % git merge origin/blead |
134 | |
6acba58e |
135 | In fact if you want to update your local repository without touching |
136 | your working directory you do: |
39219fd3 |
137 | |
138 | % git fetch |
139 | |
6acba58e |
140 | And if you want to update your remote-tracking branches for all defined |
141 | remotes simultaneously you can do |
39219fd3 |
142 | |
143 | % git remote update |
144 | |
6acba58e |
145 | Neither of these last two commands will update your working directory, |
146 | however both will update the remote-tracking branches in your |
147 | repository. |
39219fd3 |
148 | |
09081495 |
149 | To switch to another branch: |
150 | |
151 | % git checkout origin/maint-5.8-dor |
152 | |
6051489b |
153 | To make a local branch of a remote branch: |
154 | |
155 | % git checkout -b maint-5.10 origin/maint-5.10 |
156 | |
09081495 |
157 | To switch back to blead: |
158 | |
159 | % git checkout blead |
c2cf2042 |
160 | |
39219fd3 |
161 | =head2 FINDING OUT YOUR STATUS |
162 | |
163 | The most common git command you will use will probably be |
164 | |
165 | % git status |
166 | |
6acba58e |
167 | This command will produce as output a description of the current state |
168 | of the repository, including modified files and unignored untracked |
169 | files, and in addition it will show things like what files have been |
170 | staged for the next commit, and usually some useful information about |
171 | how to change things. For instance the following: |
39219fd3 |
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 |
192 | This shows that there were changes to this document staged for commit, |
193 | and that there were further changes in the working directory not yet |
194 | staged. It also shows that there was an untracked file in the working |
195 | directory, and as you can see shows how to change all of this. It also |
196 | shows that there is one commit on the working branch C<blead> which |
197 | has not been pushed to the C<origin> remote yet. B<NOTE>: that this |
198 | output is also what you see as a template if you do not provide a |
199 | message to C<git commit>. |
7f6effc7 |
200 | |
201 | Assuming 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 | |
207 | We 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 |
220 | When in doubt, before you do anything else, check your status and read |
221 | it carefully, many questions are answered directly by the git status |
222 | output. |
39219fd3 |
223 | |
c2cf2042 |
224 | =head1 SUBMITTING A PATCH |
225 | |
226 | If you have a patch in mind for Perl, you should first get a copy of |
227 | the repository: |
228 | |
229 | % git clone git://perl5.git.perl.org/perl.git perl-git |
230 | |
231 | Then change into the directory: |
232 | |
233 | % cd perl-git |
234 | |
6acba58e |
235 | Alternatively, if you already have a Perl repository, you should ensure |
236 | that you're on the I<blead> branch, and your repository is up to date: |
12322d22 |
237 | |
238 | % git checkout blead |
239 | % git pull |
240 | |
6acba58e |
241 | Now that we have everything up to date, we need to create a temporary |
242 | new branch for these changes and switch into it: |
b1fccde5 |
243 | |
a9b05323 |
244 | % git checkout -b orange |
23f8d33e |
245 | |
a9b05323 |
246 | which is the short form of |
247 | |
b1fccde5 |
248 | % git branch orange |
249 | % git checkout orange |
250 | |
c2cf2042 |
251 | Then make your changes. For example, if Leon Brocard changes his name |
252 | to Orange Brocard, we should change his name in the AUTHORS file: |
253 | |
254 | % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS |
255 | |
256 | You can see what files are changed: |
257 | |
258 | % git status |
f755e97d |
259 | # On branch orange |
c2cf2042 |
260 | # Changes to be committed: |
261 | # (use "git reset HEAD <file>..." to unstage) |
262 | # |
263 | # modified: AUTHORS |
264 | # |
265 | |
c2cf2042 |
266 | And 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 |
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 | |
283 | Now 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 | |
290 | Now you should create a patch file for all your local changes: |
291 | |
2af192ee |
292 | % git format-patch origin |
c2cf2042 |
293 | 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch |
294 | |
295 | You should now send an email to perl5-porters@perl.org with a |
296 | description of your changes, and attach this patch file as an |
297 | attachment. |
298 | |
b1fccde5 |
299 | If 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 |
307 | |
308 | =head1 ACCEPTING A PATCH |
309 | |
310 | If you have received a patch file generated using the above section, |
311 | you should try out the patch. |
312 | |
313 | First we need to create a temporary new branch for these changes and |
314 | switch into it: |
315 | |
a9b05323 |
316 | % git checkout -b experimental |
7df2e4bc |
317 | |
6acba58e |
318 | Patches that were formatted by C<git format-patch> are applied with |
319 | C<git am>: |
7df2e4bc |
320 | |
2af192ee |
321 | % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch |
7df2e4bc |
322 | Applying Rename Leon Brocard to Orange Brocard |
323 | |
6acba58e |
324 | If just a raw diff is provided, it is also possible use this two-step |
325 | process: |
09645c26 |
326 | |
327 | % git apply bugfix.diff |
328 | % git commit -am "Some fixing" --author="That Guy <that.guy@internets.com>" |
329 | |
7df2e4bc |
330 | Now 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 | |
355 | If you are a committer to Perl and you think the patch is good, you can |
75fb7651 |
356 | then merge it into blead then push it out to the main repository: |
7df2e4bc |
357 | |
358 | % git checkout blead |
d9847473 |
359 | % git merge experimental |
75fb7651 |
360 | % git push |
7df2e4bc |
361 | |
362 | If 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 |
370 | |
371 | =head1 CLEANING A WORKING DIRECTORY |
372 | |
6acba58e |
373 | The command C<git clean> can with varying arguments be used as a |
374 | replacement for make-clean. |
b0d36535 |
375 | |
376 | To reset your working directory to a pristine condition you can do: |
377 | |
378 | git clean -dxf |
379 | |
380 | However, be aware this will delete ALL untracked content. You can use |
381 | |
382 | git clean -Xf |
383 | |
6acba58e |
384 | to remove all ignored untracked files, such as build and test |
385 | byproduct, but leave any manually created files alone. |
b0d36535 |
386 | |
f755e97d |
387 | If you only want to cancel some uncommitted edits, you can use |
388 | C<git checkout> and give it a list of files to be reverted. |
389 | |
390 | If you want to cancel one or several commits, you can use C<git reset>. |
391 | |
d82a90c1 |
392 | =head1 BISECTING |
393 | |
6acba58e |
394 | C<git> provides a built-in way to determine, with a binary search in |
395 | the history, which commit should be blamed for introducing a given bug. |
d82a90c1 |
396 | |
6acba58e |
397 | Suppose that we have a script F<~/testcase.pl> that exits with C<0> |
398 | when some behaviour is correct, and with C<1> when it's faulty. We need |
399 | an helper script that automates building C<perl> and running the |
400 | testcase: |
d82a90c1 |
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 |
410 | This script may return C<125> to indicate that the corresponding commit |
411 | should be skipped. Otherwise, it returns the status of |
412 | F<~/testcase.pl>. |
d82a90c1 |
413 | |
414 | We first enter in bisect mode with: |
415 | |
416 | % git bisect start |
417 | |
6acba58e |
418 | For example, if the bug is present on C<HEAD> but wasn't in 5.10.0, |
419 | C<git> will learn about this when you enter: |
d82a90c1 |
420 | |
421 | % git bisect bad |
422 | % git bisect good perl-5.10.0 |
423 | Bisecting: 853 revisions left to test after this |
424 | |
6acba58e |
425 | This results in checking out the median commit between C<HEAD> and |
426 | C<perl-5.10.0>. We can then run the bisecting process with: |
d82a90c1 |
427 | |
428 | % git bisect run ~/run |
429 | |
430 | When 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 |
442 | You can peek into the bisecting process with C<git bisect log> and |
443 | C<git bisect visualize>. C<git bisect reset> will get you out of bisect |
444 | mode. |
d82a90c1 |
445 | |
6acba58e |
446 | Please note that the first C<good> state must be an ancestor of the |
447 | first C<bad> state. If you want to search for the commit that I<solved> |
448 | some bug, you have to negate your test case (i.e. exit with C<1> if OK |
449 | and C<0> if not) and still mark the lower bound as C<good> and the |
450 | upper as C<bad>. The "first bad commit" has then to be understood as |
451 | the "first commit where the bug is solved". |
d82a90c1 |
452 | |
6acba58e |
453 | C<git help bisect> has much more information on how you can tweak your |
454 | binary searches. |
9d68b7ed |
455 | |
456 | =head1 COMITTING TO MAINTENANCE VERSIONS |
457 | |
458 | To commit to a maintenance version of perl, you need to create a local |
459 | tracking branch: |
460 | |
461 | % git checkout --track -b maint-5.005 origin/maint-5.005 |
462 | |
f755e97d |
463 | This creates a local branch named C<maint-5.005>, which tracks the remote |
464 | branch C<origin/maint-5.005>. Then you can pull, commit, merge and push as |
6acba58e |
465 | before. |
b0d36535 |
466 | |
f755e97d |
467 | You can also cherry-pick commits from blead and another branch, by |
468 | using the C<git cherry-pick> command. It is recommended to use the B<-x> |
469 | option to C<git cherry-pick> in order to record the SHA1 of the original |
470 | commit in the new commit message. |
471 | |
472 | =head1 SEE ALSO |
473 | |
474 | The git documentation, accessible via C<git help command>. |