Using Subversion « WordPress Codex
Codex
Codex tools:
Interested in functions, hooks, classes, or methods? Check out the new
WordPress Code Reference
Using Subversion
Contents
Repository, Branches, Trunk, and Tags
Not Using Subversion
Checking Out the Code
Updating Your Copy of the Code
Exporting the Code
Browsing the Code
Developer's commands
7.1
Checking differences in your working copy
7.2
Saving patch/diff files
7.3
Applying .patch or .diff files
7.4
Reverting changes to your working copy
7.5
Switching your Working copy to another branch
Resources
This page only applies to developers, so if it's all G(r)eek to you, don't worry!
The WordPress project uses
Subversion
for code version control. Most WordPress users will never want to use Subversion, because they will only install the released versions of WordPress. However, developers of plugins and themes may want to test their software against the latest development version of WordPress, and people interested in
Contributing to WordPress
by testing or fixing bugs will need to have access to the code that is under development.
This development code is available via Subversion. In this article, we'll cover the basics of connecting to the WordPress Subversion repository and running the commands that are available to most WordPress users.
Aside from the one section on Not Using Subversion, this article assumes that you have Subversion (or at least a Subversion client) installed already, and it only covers the most basic commands. For installation instructions, alternative clients, and more detailed information, check out these resources:
Subversion web site
Subversion FAQ
Subclipse
- a Subversion plugin for the
Eclipse
development environment
TortoiseSVN
- a popular Windows Subversion client
The Subversion Book
- available free online
Note that if you choose to use TortoiseSVN, Subclipse, or another graphical client, the commands below will be menu selections -- however, the same principles apply. Check the help files for your client to figure out how to connect to the repository and execute the equivalent commands.
Repository, Branches, Trunk, and Tags
The basic idea of Subversion is that the source code and revisions are kept in a
repository
on a server. Users connect to the repository by using a
client
program, which allows the user to check out, view, edit, patch, and commit changes to the source code files (depending on the client's permission level; in the WordPress project, only a handful of people have permission to commit changes to the repository).
The WordPress repository is at
develop.svn.wordpress.org
. Within the repository, there are three sections:
trunk
develop.svn.wordpress.org/trunk
always contains the latest development code
branches
: Each major version of WordPress has its own branch which includes major and minor releases. For instance, the 3.7 branch at
develop.svn.wordpress.org/branches/3.7
is currently on version 3.7.1, which is the latest release in the 3.7 branch.
tags
: When any version is released to the public, the source code is "tagged" with the version number. So for instance, WordPress 3.7.1 can be found at
develop.svn.wordpress.org/tags/3.7.1
Starting with WordPress 3.7, the repository includes not only the source code for WordPress, but also files relating to the project's build process, unit tests and various other tools. The directory structure is thus:
trunk/src
develop.svn.wordpress.org/trunk/src
- The source code of WordPress itself
trunk/tests
develop.svn.wordpress.org/trunk/tests
- WordPress unit tests
trunk/tools
develop.svn.wordpress.org/trunk/tools
- Currently only the i18n tools
These directories can also be found within the tags and branches directories since version 3.7.
Not Using Subversion
Some people who want to test WordPress may have no interest in setting up Subversion. For those people, there are a couple of places to download development versions of WordPress:
The WordPress Beta Tester plugin
- Just install and activate this plugin on an existing WordPress install and you'll be able to choose to update to beta (under development) versions of WordPress.
wordpress.org/nightly-builds/wordpress-latest.zip
- Every night this ZIP contains the latest in-development version of WordPress.
- Trac source-code browser - navigate to the branch/tag you want (see section above), and at the bottom of the page, you will see a link to download a ZIP archive of the up-to-the-minute latest checkins on that branch/tag.
Checking Out the Code
Once you have Subversion installed, the first step you'll need to do is to
check out
the code, which basically means that you will download a version from the repository to your computer. To do this, make an empty directory for your copy of the code, change to that directory, and execute the
checkout command
on the trunk, branch, or tag you are interested in. For instance, to check out the
trunk
(latest development version):
svn co https://develop.svn.wordpress.org/trunk/
If you're only interested in the source code (and not the unit tests and build tools), you can check out the
src
subdirectory:
svn co https://develop.svn.wordpress.org/trunk/src/
After a short wait (depending on your Internet connection speed), the result will be that the directory is filled with all of the WordPress files, as well as some hidden
.svn
subdirectories containing Subversion information.
Updating Your Copy of the Code
If some time has passed since you checked out the code, and you would like to update to the latest version now available, use the
update command
, after first changing to the directory where you checked out the code originally:
svn update
Exporting the Code
If you are not planning to do any editing, updating, hacking, or bug fixing in the WordPress code, but just want to download the latest version so you can install it somewhere, you can use the
export
command (after first creating a new directory to hold the results, and changing to that directory):
svn export https://develop.svn.wordpress.org/trunk/
This will give you the same WordPress code as using
svn co
, but without the hidden
.svn
directories. None of the other Subversion commands will work after an export -- you need to do a checkout if you want to use the other Subversion commands.
Browsing the Code
To list all the files in the repository, without updating, checking out, etc, you can use the
list
command:
svn list https://develop.svn.wordpress.org/trunk/
To list files in a sub-directory, such as wp-includes:
svn list https://develop.svn.wordpress.org/trunk/src/wp-includes/
There is also an
online browser
for the WordPress Subversion repository.
Developer's commands
If you are fixing bugs in WordPress, edit the files in the directory where you checked out the code. When you are ready to submit your fixes for inclusion in an upcoming version of WordPress, read
Reporting Bugs
to find out how to create a bug ticket on
Trac
(the WordPress bug tracking system), and then use the commands below.
You may need to change to a sub-directory (such as
trunk
) to execute these commands.
Checking differences in your working copy
These commands help you understand what parts of your working copy are different from the committed version in the repository.
To get a list of the files you have changed, use the
status command
svn status
To show the changes you have made in a line-by-line
patch
format (which will also be used in exporting patches), use the
diff command
. This will output a
unified diff
of all the changes you have made to the entire tree of source code:
svn diff
To show the differences for just one file (multiple file paths can be given to show differences for a set of pages):
svn diff path/to/file
Saving patch/diff files
To share the changes you've made with other people you must export them as a .diff or .patch file (they are plain text files with the same format and either extension is fine). Once you have exported your changes as a diff file you can attach it as a patch to a
Trac
report.
For WordPress development all patches should be generated from the root of WordPress, rather than inside directories like wp-admin.
Use the diff command with > to indicate the destination file. This will save the diff output for any files changed in the current working copy.
svn diff > my-patch-file.diff
Similar to the regular diff command you can specify specific file(s) you want the diff to show differences for (useful if you have other changes in your working copy that you don't want to include in the patch)
svn diff src/wp-admin/comment.php src/wp-includes/comment.php > comments-patch-r3234.diff
Applying .patch or .diff files
To implement a .diff or .patch file into a working copy use the 'patch' command:
patch -p0 < /path/to/patch.diff
Reverting changes to your working copy
To reset your working copy to the code you checked out (to throw away any changes you've made):
svn revert . -R
You can also do a
revert
for just a single file:
svn revert path/to/file
Switching your Working copy to another branch
If you already have a working copy of the trunk, but you want to switch back to one of the released versions, you can use the '
svn switch'
command to bring all the files in your working copy back to the state of the released version. For instance, to switch back to version 3.7.1:
svn switch https://develop.svn.wordpress.org/tags/3.7.1
Resources
Using Dreamweaver to update the SVN repository
Mark Jaquith's Toolbox with Linux/Mac command-line explanations
Westi's blog post on using Tortoise SVN in Windows
Git to SVN Deploy Scripts for WordPress Plugins and Themes
Maintain and update your WordPress.org hosted plugin using Git
This article is
marked
as in need of editing. You can
help
Codex by
editing it
Retrieved from "
Categories
WordPress Development
Copyedit
Home Page
WordPress Lessons
Getting Started
Working with WordPress
Design and Layout
Advanced Topics
Troubleshooting
Developer Docs
About WordPress
Codex Resources
Community portal
Current events
Recent changes
Random page
Help