This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
trim trailing spaces
[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
8repository contains many Perl revisions from Perl 1 onwards and all
9the revisions from Perforce, the version control system we were using
10previously. This repository is accessible in different ways.
11
12The full repository takes up about 80MB of disk space. A check out of
13blead takes up about 160MB of disk space (including the repository). A
14build of blead takes up about 200MB (including the repository and the
15check out).
16
17=head1 GETTING ACCESS TO THE REPOSITORY
18
19=head2 READ ACCESS VIA THE WEB
20
21You may access this over the web. This allows you to browse the tree,
22see recent commits, search for particular commits and more. You may
23access it at:
24
25 http://perl5.git.perl.org/perl.git
26
27=head2 READ ACCESS VIA GIT
28
29You will need a copy of Git for your computer. You can fetch a copy of
30the repository using the Git protocol (which uses port 9418):
31
3b8a5fb0 32 git clone git://perl5.git.perl.org/perl.git perl-git
d7dd28b6 33
3b8a5fb0 34This clones the repository and makes a local copy in the 'perl-git'
d7dd28b6
LB
35directory.
36
37If your local network does not allow you to use port 9418, then you can
572f57ba 38fetch a copy of the repository over HTTP (this is slower):
d7dd28b6 39
3b8a5fb0 40 git clone http://perl5.git.perl.org/perl.git perl-http
d7dd28b6 41
3b8a5fb0 42This clones the repository and makes a local copy in the 'perl-http'
d7dd28b6
LB
43directory.
44
45=head2 WRITE ACCESS TO THE REPOSITORY
46
47If you are a committer, then you can fetch a copy of the repository that
48you can push back on with:
49
3b8a5fb0 50 git clone ssh://perl5.git.perl.org/gitroot/perl.git perl-ssh
d7dd28b6 51
3b8a5fb0 52This clones the repository and makes a local copy in the 'perl-ssh'
d7dd28b6
LB
53directory.
54
1a0f15d5 55If you clone using git, which is faster than ssh, then you will need to
c2cf2042 56modify your config in order to enable pushing. Edit .git/config where
1a0f15d5
YO
57you will see something like:
58
59 [remote "origin"]
60 url = git://perl5.git.perl.org/perl.git
61
62change that to something like this:
63
64 [remote "origin"]
65 url = ssh://perl5.git.perl.org/gitroot/perl.git
66
67NOTE: there are symlinks set up so that the /gitroot is actually optional.
d7dd28b6
LB
68
69=head1 OVERVIEW OF THE REPOSITORY
70
71Once you have changed into the repository directory, you can inspect it.
72
d7dd28b6 73
39219fd3
YO
74After a clone the repository will contain a single local branch, which
75will be the current branch as well, as indicated by the asterix.
76
77 % git branch
78 * blead
79
80Using the -a switch to branch will show the remote tracking branches in the
81repository:
82
83 % git branch -r
09081495 84 * blead
d7dd28b6
LB
85 origin/HEAD
86 origin/blead
87 ...
88
39219fd3
YO
89The branches that begin with "origin" correspond to the "git remote" that
90you cloned from. Each branch on the remote will be exactly tracked by theses
91branches. You should NEVER do work on these remote tracking branches. You only
92ever 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
94default branch C<blead> which will be configured to merge from the remote
95tracking branch C<origin/blead>.
96
d7dd28b6
LB
97You can see recent commits:
98
c2cf2042 99 % git log
d7dd28b6 100
23f8d33e 101And pull new changes from the repository, and update your local repository
39219fd3 102(must be clean first)
d7dd28b6
LB
103
104 % git pull
09081495 105
39219fd3
YO
106Assuming we are on the branch C<blead> immediately after a pull, this command
107would be more or less equivalent to:
108
109 % git fetch
110 % git merge origin/blead
111
112In fact if you want to update your local repository without touching your working
113directory you do:
114
115 % git fetch
116
117And if you want to update your remote tracking branches for all defined remotes
118simultaneously you do
119
120 % git remote update
121
122Neither of these last two commands will update your working directory, however
123both will update the repository.
124
09081495
LB
125To switch to another branch:
126
127 % git checkout origin/maint-5.8-dor
128
129To switch back to blead:
130
131 % git checkout blead
c2cf2042 132
39219fd3
YO
133=head2 FINDING OUT YOUR STATUS
134
135The most common git command you will use will probably be
136
137 % git status
138
23f8d33e 139This command will produce as output a description of the current state of the
39219fd3 140repository, including modified files and unignored untracked files, and in addition
23f8d33e
YO
141it will show things like what files have been staged for the next commit,
142and usually some useful information about how to change things. For instance the
39219fd3
YO
143following:
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
164This shows that there were changes to this document staged for commit, and
165that there were further changes in the working directory not yet staged. It
166also shows that there was an untracked file in the working directory, and as
167you can see shows how to change all of this. It also shows that there
168is one commit on the working branch C<blead> which has not been pushed to the
23f8d33e 169C<origin> remote yet. B<NOTE>: that this output is also what you see as a
7f6effc7
YO
170template if you do not provide a message to c<git commit>.
171
172Assuming 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
178We 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
39219fd3 190
23f8d33e 191When in doubt, before you do anything else, check your status and read it
39219fd3
YO
192carefully, many questions are answered directly by the git status output.
193
c2cf2042
LB
194=head1 SUBMITTING A PATCH
195
196If you have a patch in mind for Perl, you should first get a copy of
197the repository:
198
199 % git clone git://perl5.git.perl.org/perl.git perl-git
200
201Then change into the directory:
202
203 % cd perl-git
204
12322d22 205Alternatively, if you already have a Perl repository, you should
f5445761 206ensure that you're on the I<blead> branch, and your repository
12322d22
A
207is up to date:
208
209 % git checkout blead
210 % git pull
211
212Now that we have everything up to date, we need to create a temporary new
213branch for these changes and switch into it:
b1fccde5 214
a9b05323 215 % git checkout -b orange
23f8d33e 216
a9b05323
YO
217which is the short form of
218
b1fccde5
LB
219 % git branch orange
220 % git checkout orange
221
c2cf2042
LB
222Then make your changes. For example, if Leon Brocard changes his name
223to Orange Brocard, we should change his name in the AUTHORS file:
224
225 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
226
227You 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
c2cf2042
LB
237And 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
7df2e4bc 244 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
c2cf2042
LB
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
254Now 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
261Now you should create a patch file for all your local changes:
262
2af192ee 263 % git format-patch origin
c2cf2042
LB
264 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
265
266You should now send an email to perl5-porters@perl.org with a
267description of your changes, and attach this patch file as an
268attachment.
269
b1fccde5
LB
270If 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.
7df2e4bc
LB
278
279=head1 ACCEPTING A PATCH
280
281If you have received a patch file generated using the above section,
282you should try out the patch.
283
284First we need to create a temporary new branch for these changes and
285switch into it:
286
a9b05323 287 % git checkout -b experimental
7df2e4bc
LB
288
289Now we should apply the patch:
290
2af192ee 291 % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
7df2e4bc
LB
292 Applying Rename Leon Brocard to Orange Brocard
293
294Now 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
319If you are a committer to Perl and you think the patch is good, you can
75fb7651 320then merge it into blead then push it out to the main repository:
7df2e4bc
LB
321
322 % git checkout blead
323 % git pull . experimental
75fb7651 324 % git push
7df2e4bc
LB
325
326If 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.