Rev Author Line No. Line
185 miho 1  
2 WHY WebSVN?
3  
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
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
8 file so as to see exactly what was changed in a particular revision.
9  
10 WebSVN offers the following features:
11  
12 * Easy to use interface
13 * Highly customisable templating system
14 * Colourisation of file listings
15 * Blame view
16 * Log message searching
17 * Fast browsing thanks to internal caching feature
18 * Apache MultiViews support
19 * RSS feed support
20  
21 Since it's written using PHP, WebSVN is also very portable and easy to install.
22  
23 INSTALLATION
24  
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
27 won't currently work in safe mode, due to the need to call svnlook.
28  
29 You'll also need diff (preferably the GNU version; for Windows users I'd
30 recommend the Cygwin version) and svnlook available.
31  
32 Rename distconfig.inc as config.inc (found in the includes directory)and then
33 edit it as directed in the file itself.
34  
35 If everything has gone well, you should be able to view your projects by
36 pointing your browser at the index.php file.
37  
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.
40  
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
43 from these locations:
44  
45 Diff/Sed/Gzip/Tar: http://www.cygwin.com/
46 Enscript: http://people.ssh.com/mtr/genscript/
47  
48 ACCENTED CHARACTERS
49  
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
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
54 DLLs to the system directory (from the PHP installation directory).
55  
56 CACHING
57  
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
60 it's not generally possible to change a revision with subversion.
61  
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
64 and won't know that there's a new one available. There are various solutions
65 to this problem:
66  
67 1) Turn off caching in the config file. This will severely impede the
68 perfomance of WebSVN.
69  
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
72  
73 3) Only allow the administrator to change revision properties. He can then
74 delete the cache by hand should this occur.
75  
76 COLOURISATION
77  
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.
80  
81 Simply set the paths in the config file and then uncomment the line:
82  
83 $config->useEnscript();
84  
85 MULTIVIEWS
86  
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:
89  
90 http://servername/wsvn/repname/path/in/repository
91  
92 To do this you must:
93  
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.
96  
97 - Configure the parent directory of wsvn.php to use MultiViews (see Apache
98 docs).
99  
100 - Change config.inc to include the line $config->useMultiViews();
101  
102 - Change the paths configured at the beginning of the wsvn.php script.
103  
104 Now go to http://servername/wsvn/ and make sure that you get the index page.
105  
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.
108  
109 MULTIVIEWS EXAMPLE
110  
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:
113  
114 DocumentRoot "D:/svnpage"
115  
116 In that directory, I have WebSVN installed in a directory called websvn.
117 Normally WebSVN would be accessed by http://servername/websvn
118  
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
121 follows (based on your own directory locations, obviously):
122  
123 // Location of websvn directory via HTTP
124 //
125 // e.g. For http://servername/websvn use /websvn
126 //
127 // Note that wsvn.php need not be in the /websvn directory (and normally isn't).
128 $locwebsvnhttp = "/websvn";
129  
130 // Physical location of websvn directory
131 $locwebsvnreal = "d:/svnpage/websvn";
132  
133 Next, turn on Multiviews in the WebSVN config.inc file:
134  
135 $config->useMultiViews();
136  
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
139 .htaccess file (assuming that the appropriate AllowOverrides directive is set
140 up):
141  
142 Options MultiViews
143  
144  
145 If all has gone well, repositories should now by accessible by
146 http://servername/wsvn/repname
147  
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
150 add another directive to the .htaccess file:
151  
152 DirectoryIndex wsvn.php
153  
154 ACCESS RIGHTS AND AUTHENTICATION
155  
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
158 authentication mechanism, but that doesn't allow for per repository
159 authentication.
160  
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
163 maintain one file to define both Subversion and WebSVN access rights.
164  
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
167 the svn repositories themselves. Here's an example using SSPI:
168  
169 <Location /WebSVN/>
170 AuthType SSPI
171 SSPIAuth On
172 SSPIAuthoritative On
173 SSPIDomain IMAJEMAIL
174 SSPIOfferBasic On
175 Require valid-user
176 </Location>
177  
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.
180  
181 You should change /WebSVN/ to /wsvn/ if you're using multiviews.
182  
183 Also note that you shouldn't use the AuthzSVNAccessFile command to define the
184 access file.
185  
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
188 configure WebSVN to use your Subversion access file to control access. Add this
189 line to your config.inc file:
190  
191 $config->useAuthenticationFile("/path/to/accessfile");
192  
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
195 reach /a/b/c/. The user will not be able to see any other files or directories in
196 /a or /a/b/.
197  
198 You should read the Subversion book for information on the access file format.
199  
200 COMMON PROBLEMS
201  
202 1) On a Windows machine, this error is reported:
203  
204 Warning: shell_exec(): Unable to execute
205  
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
208 be C:\WINDOWS\system32\cmd.exe.
209  
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
212 "read" and "read & execute" boxes.
213  
214 LICENCE
215  
216 GNU Public licence.