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