Subversion

See also: History of MediaWiki version control

MediaWiki uses the Subversion version control system. To use it, you have to download the official command line Subversion client. You can also use alternative clients, such as the graphical TortoiseSVN for Windows.

Subversion's command-line interface is similar to CVS. This is a basic and partial guide of the most useful commands. For a complete guide, use the book Version Control with Subversion. If you have a write access to the server, it's very recommended that you read it and know about the advanced features of Subversion, because you might use them sooner or later.

The repository
The MediaWiki repository is hosted on mayflower, a Wikimedia server in Amsterdam, and is reachable from http://svn.wikimedia.org/svnroot/mediawiki/. The project uses a more or less standard hierarchy:


 * branches
 * tags
 * trunk

Pre-production work is made in the trunk tree. Since Wikimedia servers run the code in this tree for production usage, patches made in this tree must not break the code. You should also avoid rewriting extensive portions of the trunk as well. MediaWiki itself is in the phase3 subdirectory of the trunk.

branches is used for major coding work, testing huge patches, and testing unstable patches. Some developers have their own branch of the code here. It is also used to prepare new stable releases (through the well-known beta &rarr; release candidate &rarr; security & maintenance fix cycle). Each major stable series gets its own directory as REL_. For example, MediaWiki 1.9 work is being done in REL1_9</tt>.

tags</tt> is a special hierarchy used to save the state of the software at a given point in the time. You should NEVER make any change to it as this is only useful when releasing new versions. That task is handled solely by the MediaWiki release manager (Tim Starling).

There is an additional subproject named wikimedia-web</tt>, which hosts the Wikimedia portal files located at http://www.wikimedia.org/. You usually don't want to modify anything there without referring to the Wikimedia Foundation and/or the Wikimedia system administrators.

Anonymous use (using Subversion)
If you don't have write access to the repository, you have to access it anonymously, via regular HTTP. However, most of the techniques shown here may be useful also for developer use, so please read it even if you don't have to access the server anonymously. If you plan on committing, you'll want to checkout using  instead of   (see Commit_access.) If you checkout using   and then need to switch to , use.

Check out
First, you have to check out the code of MediaWiki. Use the following syntax: svn checkout http://svn.wikimedia.org/svnroot/mediawiki/folders_to_download sub_folder_name

You can browse the code structure using the web interface (ViewVC). Use the three folders there for different purposes:
 * Trunk is the main development branch.
 * The branches are used for stable versions of the core and for versions of extensions that work with those stable versions; and for the development of complex features.
 * The tags are used to track the released versions.

The URL structure is:


 * transport : http://svn.wikimedia.org
 * repository : /svnroot/mediawiki
 * branch/tag : /trunk, or /branches/REL1_9, or /tags/REL1_9_0
 * files : /phase3

Unlike the old CVS, the URL is used to specify the branch or the tag.

Don't leave off the "trunk" or branch part! If you leave that off you check out every revision of every file in the repo, which is pretty silly.

To check out MediaWiki development trunk into the folder "wiki": svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/phase3 wiki

To check out the extensions set into the folder "extensions": svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions extensions

To check out the latest bits in some particular release branch: svn checkout http://svn.wikimedia.org/svnroot/mediawiki/branches/REL1_9/phase3 REL1_9

To check out a specific version of the software: svn checkout http://svn.wikimedia.org/svnroot/mediawiki/tags/REL1_9_0/phase3 REL1_9_0

To check out a specific development revision of the software: (for example the one used there: )

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/phase3@ wiki or svn checkout -r http://svn.wikimedia.org/svnroot/mediawiki/trunk/phase3 wiki or, if you want to switch to that revision, use update command: svn update -r

Unlike the old CVS, anonymous access is completely up to date, so you can grab fixes immediately after they get committed.

Updating the working copy
To update your working copy and get the latest files, use the following command:

svn update #or just: "svn up"

Note that SVN, unlike CVS, doesn't need to be told to prune removed files or create new directories. This is automagic.

For a simple way to keep abreast of changes, one could use e.g., cp RELEASE-NOTES /tmp && svn up && diff /tmp RELEASE-NOTES

Conflict discovered in 'includes/NeurdBall.php'. Select: (p) postpone, (df) diff-full, (e) edit, (h) help for more options:
 * What happens if I change some file, then do "svn up" and it was changed upstream too?
 * Don't worry. You will see

Making a diff
Diffs, or patches, are text files which include all the changes done in the working copy. If you suggest a new feature in Bugzilla and like to suggest a change which fixes it, upload a patch.

To create a diff from the current repository, use the following command:

svn diff

Normally, unlike CVS, you don't have to tell SVN which files you changed; however, you may like to diff only a part of the repository. To do that, specify the files to diff:

svn diff includes/SpecialMyAwesomePage.php

Note that SVN defaults to the "unified" diff format, so the "-u" option doesn't have to be passed.

Applying a diff
Subversion does not contain a built in command to apply diffs to the current working copy (for example, to review or commit diffs published in Bugzilla); instead, you can use the regular patch unix utility: patch -p0 < patch_file

TortoiseSVN has a built-in support for applying a diff.

Changing file structure
You can add files or folders to the working copy, to be included in the next diff or commit, using the command: svn add file.name

If you add a folder, it will add all the files included in the folder, except for files in the ignored list.

You can delete files or folders from the working copy, to be deleted in the next commit or marked as such in the next diff, using the command (which will automatically delete the files from the working copy, but won't delete folders in such way): svn delete file.name

Make sure the file or folder do not have local modifications, else they won't be deleted unless you force the deletion.

Reverting your changes
If your changes in the working copy are not useful in your opinion, you can revert them using the following command: svn revert

You must use parameters for this command. To revert all your changes in the working copy, use: svn revert -R.

To revert the changes in a specific file, use: svn revert file.name

Reverting can also remove added files (they won't be deleted, just removed and considered "unknown files", just like you didn't use  at first), and restore deleted files (both deleted by hand and deleted by  ).

Checking the status of the working copy
You can check the status of your working copy using the following command: svn status

These are several important letters in the first column of the item, which show the status:
 * M = the item was modified by you
 * A = the item was added by you (using )
 * D = the item was deleted by you (using )
 * ? = the item is not under the version control, but exists
 * ! = the item is missing (under the version control, but does not exist - probably deleted without using ) or incomplete

Developer use
If you have a write access for the server, you can use an SSH access instead of HTTP access. This might change later.

You can request access at the commit access requests page.

URLs
Replace the server name  to   in all the commands (e.g. svn checkout), then you will be able to use the normal functions, when you will have to enter your passphrase for a function that requires web access. Sometimes you will be required to enter your passphrase more than once. If you will make a mistake in the passphrase, you will be requested to type it again.

For example, to check out the latest trunk as an anonymous, you use: svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/phase3 wiki

To check it out as a developer, use: svn checkout svn+ssh://your_user_name@svn.wikimedia.org/svnroot/mediawiki/trunk/phase3 wiki

Note that in order for this to work you must have added your identity to the ssh authentication agent. For example, if your secret key is presently located at, you must add it using: ssh-add /home/tux/.ssh/tux.key

Windows users
Windows users of subversion client may need to follow the instructions mentioned here to make the tool use their SSH public key (or if you are using TortoiseSVN, checkout this how-to guide).

Auto properties
See Subversion/auto-props for how to enable automatic line-ending conversion for files you add. Every developer should use it.

Commits
Commits, or check ins, are the action of applying your changes from the working copy to the web repository. Use the following command to do that: svn commit

Using the command without the parameters will fail, unless you've configured an editor, because you have to enter a comment for the file logs. You can use one of the following forms: svn commit --message="This is the log comment." svn commit --file=file_with_log_comment

If, in your log message, you refer to variables using PHP's '$' notation, remember to escape them from the shell.

To cause an extension to show up under the correct version in Special:ExtensionDistributor, add your extension to the corresponding extensions branch in, for example.

Using the GitHub mirror
There's a mirror of the MediaWiki SVN repository at GitHub. To use it:

First clone the repository:

git svn clone git://github.com/mediawiki/mediawiki-svn.git

This will take a while. The repository is around 360MB.

Commiting back from this mirror is currently unsupported. See this thread on the Git mailing list for why. The gist of it is that it's hard to reconstruct the SVN metadata needed to push back to the original SVN.

What you can do instead is this:

Check out a limited part of the repository instead of the whole thing, right now there are trunk/phase3 and trunk/extensions mirrors:

git clone git://github.com/mediawiki/mediawiki-trunk-phase3.git

or:

git clone git://github.com/mediawiki/mediawiki-trunk-extensions.git

Hack there on your own branch and keep syncing with upstream. Then when you're ready to push back create your own mirror (or ask avar for an up to date copy):

git svn clone svn+ssh://svn.wikimedia.org/svnroot/mediawiki/trunk/phase3

Then just move your commits between the two repositories. E.g. with  in the original followed by   in the other.

Converting a CVS checkout to SVN
Assuming you don't want to keep any local changes to files in the repository, it's easy to just overwrite everything with a fresh checkout. This will keep your local files, such as LocalSettings.php and custom skins.

svn co http://svn.wikimedia.org/svnroot/mediawiki/trunk/phase3 temp-checkout rsync -a temp-checkout/ /path/to/phase3/

The following works if you didn't delete any directories:

svn revert -R /path/to/phase3

And if you want to get rid of the old CVS dirs:

find. -type d -name CVS -print0 | xargs -0r rm -rf

Be careful with that one. ;)

If you don't have SVN or can't use it
At http://toolserver.org/~vvv/mw-nightly/ you can find snapshots of trunk and extensions, updated daily.