Rev 172 Rev 185
1   1  
2 WHY WebSVN? 2 WHY WebSVN?
3   3  
4 WebSVN offers a view onto your subversion repositories that's been designed 4 WebSVN offers a view onto your subversion repositories that's been designed
5 to reflect the Subversion methodology. You can view the log of any file or 5 to reflect the Subversion methodology. You can view the log of any file or
6 directory and see a list of all the files changed, added or deleted in any 6 directory and see a list of all the files changed, added or deleted in any
7 given revision. You can also view the differences between 2 versions of a 7 given revision. You can also view the differences between 2 versions of a
8 file so as to see exactly what was changed in a particular revision. 8 file so as to see exactly what was changed in a particular revision.
9   9  
10 WebSVN offers the following features: 10 WebSVN offers the following features:
11   11  
12 * Easy to use interface 12 * Easy to use interface
13 * Highly customisable templating system 13 * Highly customisable templating system
14 * Colourisation of file listings 14 * Colourisation of file listings
15 * Blame view 15 * Blame view
16 * Log message searching 16 * Log message searching
17 * Fast browsing thanks to internal caching feature 17 * Fast browsing thanks to internal caching feature
18 * Apache MultiViews support 18 * Apache MultiViews support
19 * RSS feed support 19 * RSS feed support
20   20  
21 Since it's written using PHP, WebSVN is also very portable and easy to install. 21 Since it's written using PHP, WebSVN is also very portable and easy to install.
22   22  
23 INSTALLATION 23 INSTALLATION
24   24  
25 Grab the source and stick it somewhere that your server can get to. You 25 Grab the source and stick it somewhere that your server can get to. You
26 obviously need to have PHP installed and working. Also note that WebSVN 26 obviously need to have PHP installed and working. Also note that WebSVN
27 won't currently work in safe mode, due to the need to call svnlook. 27 won't currently work in safe mode, due to the need to call svnlook.
28   28  
29 You'll also need diff (preferably the GNU version; for Windows users I'd 29 You'll also need diff (preferably the GNU version; for Windows users I'd
30 recommend the Cygwin version) and svnlook available. 30 recommend the Cygwin version) and svnlook available.
31   31  
32 Rename distconfig.inc as config.inc (found in the includes directory)and then 32 Rename distconfig.inc as config.inc (found in the includes directory)and then
33 edit it as directed in the file itself. 33 edit it as directed in the file itself.
34   34  
35 If everything has gone well, you should be able to view your projects by 35 If everything has gone well, you should be able to view your projects by
36 pointing your browser at the index.php file. 36 pointing your browser at the index.php file.
37   37  
38 For those of you wishing to customise the look and feel a little, you should 38 For those of you wishing to customise the look and feel a little, you should
39 read templates.txt, which explains the highly configurable template system. 39 read templates.txt, which explains the highly configurable template system.
40   40  
41 Windows users - note that some of the features offered by WebSVN, when 41 Windows users - note that some of the features offered by WebSVN, when
42 enabled, require the use of various external programs. They can be downloaded 42 enabled, require the use of various external programs. They can be downloaded
43 from these locations: 43 from these locations:
44   44  
45 Diff/Sed/Gzip/Tar: http://www.cygwin.com/ 45 Diff/Sed/Gzip/Tar: http://www.cygwin.com/
46 Enscript: http://people.ssh.com/mtr/genscript/ 46 Enscript: http://people.ssh.com/mtr/genscript/
47   47  
48 ACCENTED CHARACTERS 48 ACCENTED CHARACTERS
49   49  
50 WebSVN is designed to worked with accented characters. To do this, it uses 50 WebSVN is designed to worked with accented characters. To do this, it uses
51 the iconv function. This may not be installed on your system. If you aren't 51 the iconv function. This may not be installed on your system. If you aren't
52 getting the characters that you expect, make sure that the iconv module is 52 getting the characters that you expect, make sure that the iconv module is
53 being loaded in php.ini. Windows users will need to copy the appropriate 53 being loaded in php.ini. Windows users will need to copy the appropriate
54 DLLs to the system directory (from the PHP installation directory). 54 DLLs to the system directory (from the PHP installation directory).
55   55  
56 CACHING 56 CACHING
57   57  
58 In order to return results with a reasonable speed, WebSVN caches the results 58 In order to return results with a reasonable speed, WebSVN caches the results
59 of it's requests to svnlook. Under normal usage this works correctly since 59 of it's requests to svnlook. Under normal usage this works correctly since
60 it's not generally possible to change a revision with subversion. 60 it's not generally possible to change a revision with subversion.
61   61  
62 That said, one case that may cause confusion is if someone changes the log 62 That said, one case that may cause confusion is if someone changes the log
63 message of a given revision. WebSVN will have cached the previous log message 63 message of a given revision. WebSVN will have cached the previous log message
64 and won't know that there's a new one available. There are various solutions 64 and won't know that there's a new one available. There are various solutions
65 to this problem: 65 to this problem:
66   66  
67 1) Turn off caching in the config file. This will severely impede the 67 1) Turn off caching in the config file. This will severely impede the
68 perfomance of WebSVN. 68 perfomance of WebSVN.
69   69  
70 2) Change the post-revprop-change hook so that is deletes the contents of the 70 2) Change the post-revprop-change hook so that is deletes the contents of the
71 cache after any change to a revision property 71 cache after any change to a revision property
72   72  
73 3) Only allow the administrator to change revision properties. He can then 73 3) Only allow the administrator to change revision properties. He can then
74 delete the cache by hand should this occur. 74 delete the cache by hand should this occur.
75   75  
76 COLOURISATION 76 COLOURISATION
77   77  
78 You can few files with syntax colouring if you have Enscript 1.6 or higher 78 You can few files with syntax colouring if you have Enscript 1.6 or higher
79 installed on your system. You'll also need Sed. 79 installed on your system. You'll also need Sed.
80   80  
81 Simply set the paths in the config file and then uncomment the line: 81 Simply set the paths in the config file and then uncomment the line:
82   82  
83 $config->useEnscript(); 83 $config->useEnscript();
84   84  
85 MULTIVIEWS 85 MULTIVIEWS
86   86  
87 You may choose to configure access to your repository via Apache's MultiView 87 You may choose to configure access to your repository via Apache's MultiView
88 system. This will enable you to access a respositoy using a url such as: 88 system. This will enable you to access a respositoy using a url such as:
89   89  
90 http://servername/wsvn/repname/path/in/repository 90 http://servername/wsvn/repname/path/in/repository
91   91  
92 To do this you must: 92 To do this you must:
93   93  
94 - Place wsvn.php where you want to. Normally you place it such that it's 94 - Place wsvn.php where you want to. Normally you place it such that it's
95 accessible straight after the servername, as shown above. 95 accessible straight after the servername, as shown above.
96   96  
97 - Configure the parent directory of wsvn.php to use MultiViews (see Apache 97 - Configure the parent directory of wsvn.php to use MultiViews (see Apache
98 docs). 98 docs).
99   99  
100 - Change config.inc to include the line $config->useMultiViews(); 100 - Change config.inc to include the line $config->useMultiViews();
101   101  
102 - Change the paths configured at the beginning of the wsvn.php script. 102 - Change the paths configured at the beginning of the wsvn.php script.
103   103  
104 Now go to http://servername/wsvn/ and make sure that you get the index page. 104 Now go to http://servername/wsvn/ and make sure that you get the index page.
105   105  
106 The repname part of the URL is the name given to it in the config.inc file. 106 The repname part of the URL is the name given to it in the config.inc file.
107 For this reason you may wish to avoid putting spaces in the name. 107 For this reason you may wish to avoid putting spaces in the name.
108   108  
109 MULTIVIEWS EXAMPLE 109 MULTIVIEWS EXAMPLE
110   110  
111 First, you must get the Multiviews option working. In my set up, my Apache 111 First, you must get the Multiviews option working. In my set up, my Apache
112 directory root is set to a location on my harddrive: 112 directory root is set to a location on my harddrive:
113   113  
114 DocumentRoot "D:/svnpage" 114 DocumentRoot "D:/svnpage"
115   115  
116 In that directory, I have WebSVN installed in a directory called websvn. 116 In that directory, I have WebSVN installed in a directory called websvn.
117 Normally WebSVN would be accessed by http://servername/websvn 117 Normally WebSVN would be accessed by http://servername/websvn
118   118  
119 wsvn.php in then copied from the WebSVN installation to the document root 119 wsvn.php in then copied from the WebSVN installation to the document root
120 directory and the variables at the beginning of the script configured as 120 directory and the variables at the beginning of the script configured as
121 follows (based on your own directory locations, obviously): 121 follows (based on your own directory locations, obviously):
122   122  
123 // Location of websvn directory via HTTP 123 // Location of websvn directory via HTTP
124 // 124 //
125 // e.g. For http://servername/websvn use /websvn 125 // e.g. For http://servername/websvn use /websvn
126 // 126 //
127 // Note that wsvn.php need not be in the /websvn directory (and normally isn't). 127 // Note that wsvn.php need not be in the /websvn directory (and normally isn't).
128 $locwebsvnhttp = "/websvn"; 128 $locwebsvnhttp = "/websvn";
129   129  
130 // Physical location of websvn directory 130 // Physical location of websvn directory
131 $locwebsvnreal = "d:/svnpage/websvn"; 131 $locwebsvnreal = "d:/svnpage/websvn";
132   132  
133 Next, turn on Multiviews in the WebSVN config.inc file: 133 Next, turn on Multiviews in the WebSVN config.inc file:
134   134  
135 $config->useMultiViews(); 135 $config->useMultiViews();
136   136  
137 Finally, Apache needs to know that you want to enable MultiViews for the root 137 Finally, Apache needs to know that you want to enable MultiViews for the root
138 directory. This can be done by including this line in the directory's 138 directory. This can be done by including this line in the directory's
139 .htaccess file (assuming that the appropriate AllowOverrides directive is set 139 .htaccess file (assuming that the appropriate AllowOverrides directive is set
140 up): 140 up):
141   141  
142 Options MultiViews 142 Options MultiViews
143   143  
144   144  
145 If all has gone well, repositories should now by accessible by 145 If all has gone well, repositories should now by accessible by
146 http://servername/wsvn/repname 146 http://servername/wsvn/repname
147   147  
148 Note the index page can be accessed through http://servername/wsvn 148 Note the index page can be accessed through http://servername/wsvn
149 If you want to view the index page by http://servername/ you need to 149 If you want to view the index page by http://servername/ you need to
150 add another directive to the .htaccess file: 150 add another directive to the .htaccess file:
151   151  
152 DirectoryIndex wsvn.php 152 DirectoryIndex wsvn.php
153   153  
154 ACCESS RIGHTS AND AUTHENTICATION 154 ACCESS RIGHTS AND AUTHENTICATION
155   155  
156 You may wish to provide an authentication mechanism for WebSVN. One obvious 156 You may wish to provide an authentication mechanism for WebSVN. One obvious
157 solution is to protect the entire WebSVN directory with some form of Apache 157 solution is to protect the entire WebSVN directory with some form of Apache
158 authentication mechanism, but that doesn't allow for per repository 158 authentication mechanism, but that doesn't allow for per repository
159 authentication. 159 authentication.
160   160  
161 WebSVN provides and access rights mechanism that uses your SVN access file to 161 WebSVN provides and access rights mechanism that uses your SVN access file to
162 control read access to the repository. This means that you only have to 162 control read access to the repository. This means that you only have to
163 maintain one file to define both Subversion and WebSVN access rights. 163 maintain one file to define both Subversion and WebSVN access rights.
164   164  
165 For this to work, you need to configure your authentication method to the /WebSVN/ 165 For this to work, you need to configure your authentication method to the /WebSVN/
166 (or /wsvn/) directory. This should be the same authentication as you use for 166 (or /wsvn/) directory. This should be the same authentication as you use for
167 the svn repositories themselves. Here's an example using SSPI: 167 the svn repositories themselves. Here's an example using SSPI:
168   168  
169 <Location /WebSVN/> 169 <Location /WebSVN/>
170 AuthType SSPI 170 AuthType SSPI
171 SSPIAuth On 171 SSPIAuth On
172 SSPIAuthoritative On 172 SSPIAuthoritative On
173 SSPIDomain IMAJEMAIL 173 SSPIDomain IMAJEMAIL
174 SSPIOfferBasic On 174 SSPIOfferBasic On
175 Require valid-user 175 Require valid-user
176 </Location> 176 </Location>
177   177  
178 Note the use of the / after /WebSVN/ in the location directive. If you use 178 Note the use of the / after /WebSVN/ in the location directive. If you use
179 <Location /WebSVN> then you won't be able to access the index. 179 <Location /WebSVN> then you won't be able to access the index.
180   180  
181 You should change /WebSVN/ to /wsvn/ if you're using multiviews. 181 You should change /WebSVN/ to /wsvn/ if you're using multiviews.
182   182  
183 Also note that you shouldn't use the AuthzSVNAccessFile command to define the 183 Also note that you shouldn't use the AuthzSVNAccessFile command to define the
184 access file. 184 access file.
185   185  
186 Now that you've defined your authentication, you'll be asked for your user name 186 Now that you've defined your authentication, you'll be asked for your user name
187 and password in order to access the WebSVN directory. All that's left is to 187 and password in order to access the WebSVN directory. All that's left is to
188 configure WebSVN to use your Subversion access file to control access. Add this 188 configure WebSVN to use your Subversion access file to control access. Add this
189 line to your config.inc file: 189 line to your config.inc file:
190   190  
191 $config->useAuthenticationFile("/path/to/accessfile"); 191 $config->useAuthenticationFile("/path/to/accessfile");
192   192  
193 Note that if your access file gives read access to, for example, path /a/b/c/ but 193 Note that if your access file gives read access to, for example, path /a/b/c/ but
194 not to /a/b/, then the user will be given restricted access to /a/b/ in order to 194 not to /a/b/, then the user will be given restricted access to /a/b/ in order to
195 reach /a/b/c/. The user will not be able to see any other files or directories in 195 reach /a/b/c/. The user will not be able to see any other files or directories in
196 /a or /a/b/. 196 /a or /a/b/.
197   197  
198 You should read the Subversion book for information on the access file format. 198 You should read the Subversion book for information on the access file format.
199   199  
200 COMMON PROBLEMS 200 COMMON PROBLEMS
201   201  
202 1) On a Windows machine, this error is reported: 202 1) On a Windows machine, this error is reported:
203   203  
204 Warning: shell_exec(): Unable to execute 204 Warning: shell_exec(): Unable to execute
205   205  
206 If you experience this problem, you need to give IUSR_<machinename> execute 206 If you experience this problem, you need to give IUSR_<machinename> execute
207 permissions on %systemroot%\system32\cmd.exe. Under most systems, the file will 207 permissions on %systemroot%\system32\cmd.exe. Under most systems, the file will
208 be C:\WINDOWS\system32\cmd.exe. 208 be C:\WINDOWS\system32\cmd.exe.
209   209  
210 Right-click on the file, choose properties, and on the security tab click 210 Right-click on the file, choose properties, and on the security tab click
211 the "Add" button. Add the IUSR_<machinename> user, and then select the 211 the "Add" button. Add the IUSR_<machinename> user, and then select the
212 "read" and "read & execute" boxes. 212 "read" and "read & execute" boxes.
213   213  
214 LICENCE 214 LICENCE
215   215  
216 GNU Public licence. 216 GNU Public licence.