Using Subversion for WordPress Plugins
Subversion Control for WordPress
If you write a plugin for WordPress and want to make it available on WordPress.org, you have to use Subversion to handle revisions, versions and source control.
There are a number of programs that you can use and which can be installed on a PC or a MAC. Many do use the command line which can be difficult for those not familiar with the particular commands. However, there are a number of client applications that have very good user interfaces which does make the process much easier.
SilkSVN Windows Command Line Client. https://sliksvn.com/download/
TortoiseSVN for Windows which can be downloaded at https://tortoisesvn.net/downloads.html
Versions for the Mac which can be downloaded at http://versionsapp.com
When I first began to look at WordPress and SVN, I wanted to use a visual method of updating. I wanted to click a button and for it to automatically do everything without thinking. However, I found that using a visual interface did not show the point of SVN and when I started to use a text interface, I found I understood the process much better. Also there is a lot of documentation available for the command line interface which is helpful when things go wrong.
The following are some notes that I have made over the years about using the command line system with WordPress which may help if you are having issues. It is based on the WordPress.org documentation but I have added in some extra points.
Command Line SVN
As I use Windows I use SilkSVN. Download and install SilkSVN and in the cmd terminal (go to Windows Start and enter cmd.exe), type “svn” followed by the required commands. “svn help” will show help text and will show that SilkSVN is working.
The documentation that WordPress has produced is located here:
The only issue I have found when using SilkSVN is that you should use double quotes wherever it uses single quotes as in the standard SVN documentation.
Also, always make sure you change directory to where your local repository is located.
Starting a new plugin
On your computer, first create a local directory which will be your copy of the SVN repository.
In this document I will use my-local-dir to refer to the local directory.
Next, check out the pre-built repository using the co command:
my-local-dir / svn co https://plugins.svn.wordpress.org/your-plugin-name my-local-dir > A my-local-dir/trunk > A my-local-dir/branches > A my-local-dir/tags > Checked out revision 11325.
You will probably be asked your username and password which will be the one you were given when you registered for WordPress.org.
The above command will create a set of folders on your local computer in your local directory called “trunk”, “branches” and “tags”.
The “tags” folder is for your releases and will consist of a number of sub folders that correspond to your version numbers.
The “trunk” folder is where your development version is located.
Copy your files into the “trunk” folder and then you have to let subversion know you want to add the files into the repository:
my-local-dir / svn add trunk/*
Now check in the changes:
my-local-dir / svn ci -m "Check in to trunk"
Now copy the trunk files to the required tag folder. In this example I am going to create a folder 1.0.0
my-local-dir / svn cp trunk tags/1.0.0 > A tags/1.0.0
and commit the changes:
my-local-dir / svn ci -m "tagging version 1.0.0"
So now on the remote repository you should have your released files in the tag/1.0.0 and your current working development files will also be in the “trunk” folder.
Creating a new version
We want to create a new version of our plugin so we:
* Modify the readme.txt with the new version number.
* Modify the main php file with the new version number.
* Update the trunk folder so that it contains the latest files.
* Copy the trunk folder to a new tags folder using SVN.
* Check in the changes using SVN.
Essentially the method is the same as described above but with a few more checks.
On your local computer, make sure that your trunk files are up to date.
We can do this by using the SVN update command. (First, change your directory to where the SVN local directory is situated):
my-local-dir / svn update
Files in the remote repository are downloaded and update the local files.
Copy over the file or files to your local trunk folder and then let subversion know you want to add those files back:
my-local-dir / svn add trunk/*
Now commit the changes:
my-local-dir / svn ci –m “add new files to trunk”
Now do a status display:
my-local-dir / svn stat
You can see the meaning of the status information further at the end of this article.
At this point, you may have to delete files / folders by:
my-local-dir / svn delete
In some cases, you may have to use –force to force the deletion.
When you do:
my-local-dir / svn stat
you should now see those files/folders marked for deletion.
Deleting only deletes it form the local copy and only schedules if for deletion from the repository. You have to then commit the changes by:
my-local-dir / svn ci -m "New files update" > Sending trunk/my-plugin.php > Transmitting file data . > Committed revision 11327.
That updates the files in the trunk folder and deletes any marked files.
Now that you have the files checked in to the trunk folder, you can copy over the files to a tag folder as described above.
You do this by:
my-local-dir / svn cp trunk tags/2.0 > A tags/2.0
Now, as always, check in the changes.
my-local-dir / svn ci -m "tagging version 2.0" > Adding tags/2.0 > Adding tags/2.0/my-plugin.php > Adding tags/2.0/readme.txt > Committed revision 11328.
The assets folder
Use the assets folder for files like screenshots, banners and icons for wordpress.org site. Note that the assets folder is a separate folder in the root of the folder structure and is not a subfolder of the trunk or tag folder.
Update as the assets folder follows.
Navigate to the local folder which is the root of the SVN, then enter:
my-local-dir / svn add assets/* > A assets/sceenshot-1.png > A assets/sceenshot-2.png
The “add assets/*” identifies all files in the assets folder.
After you add all your files, you need to check in the changes back to the central repository using ci:
my-local-dir / svn ci -m “Add assets” > Adding assets/screenshot-1.png > Adding assets/screenshot-2.png > Transmitting file data > Committed revision 1124545
A useful command is “svn status” which gives information about the state of the repository.
my-local-dir / svn stat
If you see ? in the list of files or folders, it means that they are not under svn control. In which case do “svn add
To use this command as with all the other commands, you need to change directory on your local computer to the root folder of the SVN.
U: Working file was updated
G: Changes on the repository were automatically merged into the working copy
M: Working copy is modified
C: This file conflicts with the version in the repository
?: This file is not under version control
!: This file is under version control but is missing or incomplete
A: This file will be added to version control (after commit)
A+: This file will be moved (after commit)
D: This file will be deleted (after commit)
S: This signifies that the file or directory has been switched from the path of the rest of the working copy (using svn switch) to a branch
X: External definition
~: Type changed
R: Item has been replaced in your working copy. This means the file was scheduled for deletion, and then a new file with the same name was scheduled for addition in its place.
L : Item is locked
E: Item existed, as it would have been created, by an SVN update.
Problems, problems, problems
If you get a message ‘folder name’ is scheduled for addition, but is missing then look at the following document:
Also look at:
The method that I have found to use is rm (remove), or you may use the delete command. So you do something like:
my-local-dir / svn rm –force c:\csv\withinweb_wp_keycodes\withinweb-php-keycodes\tags\2.0.0\views
Once you have removed all the problems you should be able to commit.
Note that you may have change the local directory to the file or folder that you are going to delete or you have to enter the full path name of the file or folder.
Checking files are at the correct version can be done by doing a diff.