This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Really ignore .patch files
[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
73The repository contains a few branches:
74
09081495
LB
75 % git branch -a
76 * blead
d7dd28b6
LB
77 origin/HEAD
78 origin/blead
79 ...
80
81You can see recent commits:
82
c2cf2042 83 % git log
d7dd28b6
LB
84
85And pull new changes from the repository:
86
87 % git pull
09081495
LB
88
89To switch to another branch:
90
91 % git checkout origin/maint-5.8-dor
92
93To switch back to blead:
94
95 % git checkout blead
c2cf2042
LB
96
97=head1 SUBMITTING A PATCH
98
99If you have a patch in mind for Perl, you should first get a copy of
100the repository:
101
102 % git clone git://perl5.git.perl.org/perl.git perl-git
103
104Then change into the directory:
105
106 % cd perl-git
107
12322d22 108Alternatively, if you already have a Perl repository, you should
f5445761 109ensure that you're on the I<blead> branch, and your repository
12322d22
A
110is up to date:
111
112 % git checkout blead
113 % git pull
114
115Now that we have everything up to date, we need to create a temporary new
116branch for these changes and switch into it:
b1fccde5
LB
117
118 % git branch orange
119 % git checkout orange
120
c2cf2042
LB
121Then make your changes. For example, if Leon Brocard changes his name
122to Orange Brocard, we should change his name in the AUTHORS file:
123
124 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
125
126You can see what files are changed:
127
128 % git status
129 # On branch blead
130 # Changes to be committed:
131 # (use "git reset HEAD <file>..." to unstage)
132 #
133 # modified: AUTHORS
134 #
135
c2cf2042
LB
136And you can see the changes:
137
138 % git diff
139 diff --git a/AUTHORS b/AUTHORS
140 index 293dd70..722c93e 100644
141 --- a/AUTHORS
142 +++ b/AUTHORS
7df2e4bc 143 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
c2cf2042
LB
144 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
145 Leif Huhn <leif@hale.dkstat.com>
146 Len Johnson <lenjay@ibm.net>
147 -Leon Brocard <acme@astray.com>
148 +Orange Brocard <acme@astray.com>
149 Les Peters <lpeters@aol.net>
150 Lesley Binks <lesley.binks@gmail.com>
151 Lincoln D. Stein <lstein@cshl.org>
152
153Now commit your change locally:
154
155 % git add AUTHORS
156 % git commit -m 'Rename Leon Brocard to Orange Brocard'
157 Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
158 1 files changed, 1 insertions(+), 1 deletions(-)
159
160Now you should create a patch file for all your local changes:
161
2af192ee 162 % git format-patch origin
c2cf2042
LB
163 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
164
165You should now send an email to perl5-porters@perl.org with a
166description of your changes, and attach this patch file as an
167attachment.
168
b1fccde5
LB
169If you want to delete your temporary branch, you may do so with:
170
171 % git checkout blead
172 % git branch -d orange
173 error: The branch 'orange' is not an ancestor of your current HEAD.
174 If you are sure you want to delete it, run 'git branch -D orange'.
175 % git branch -D orange
176 Deleted branch orange.
7df2e4bc
LB
177
178=head1 ACCEPTING A PATCH
179
180If you have received a patch file generated using the above section,
181you should try out the patch.
182
183First we need to create a temporary new branch for these changes and
184switch into it:
185
186 % git branch experimental
187 % git checkout experimental
188
189Now we should apply the patch:
190
2af192ee 191 % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
7df2e4bc
LB
192 Applying Rename Leon Brocard to Orange Brocard
193
194Now we can inspect the change:
195
196 % git log
197 commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
198 Author: Leon Brocard <acme@astray.com>
199 Date: Fri Dec 19 17:02:59 2008 +0000
200
201 Rename Leon Brocard to Orange Brocard
202 ...
203
204 % git diff blead
205 diff --git a/AUTHORS b/AUTHORS
206 index 293dd70..722c93e 100644
207 --- a/AUTHORS
208 +++ b/AUTHORS
209 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
210 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
211 Leif Huhn <leif@hale.dkstat.com>
212 Len Johnson <lenjay@ibm.net>
213 -Leon Brocard <acme@astray.com>
214 +Orange Brocard <acme@astray.com>
215 Les Peters <lpeters@aol.net>
216 Lesley Binks <lesley.binks@gmail.com>
217 Lincoln D. Stein <lstein@cshl.org>
218
219If you are a committer to Perl and you think the patch is good, you can
75fb7651 220then merge it into blead then push it out to the main repository:
7df2e4bc
LB
221
222 % git checkout blead
223 % git pull . experimental
75fb7651 224 % git push
7df2e4bc
LB
225
226If you want to delete your temporary branch, you may do so with:
227
228 % git checkout blead
229 % git branch -d experimental
230 error: The branch 'experimental' is not an ancestor of your current HEAD.
231 If you are sure you want to delete it, run 'git branch -D experimental'.
232 % git branch -D experimental
233 Deleted branch experimental.