A Developer’s Guide to Using SVN for WordPress Plugin Development

As a WordPress plugin developer, version control is crucial for managing your code. While many developers prefer Git, Subversion (SVN) remains the official version control system for the WordPress.org plugin repository. In this guide, I’ll walk you through the essentials of using SVN for WordPress plugin development.

Why Use SVN?

SVN is the required version control system for submitting plugins to the WordPress.org repository. It allows you to:

1. Track changes in your code
2. Collaborate with other developers
3. Manage different versions of your plugin
4. Easily update your plugin on WordPress.org

Getting Started with SVN

1. Install SVN

First, you’ll need to install SVN on your local machine. The installation process varies depending on your operating system. For the most up-to-date installation instructions specific to your OS, visit Apache Subversion Packages.

This page provides official Apache Subversion binary packages for various operating systems, including Windows, macOS, and different Linux distributions. Follow the instructions for your specific OS to ensure you install the correct version of SVN.

After installation, you can verify that SVN is correctly installed by opening a terminal or command prompt and typing:

svn --version

This command should display the version of SVN installed on your system.

2. Set Up Your SVN Repository

When your plugin is approved for the WordPress.org repository, you’ll receive an SVN URL. It will look something like this:

https://plugins.svn.wordpress.org/your-plugin-name/

To start working with your plugin locally, you’ll need to check out (clone) the repository to your local machine. Use the following command in your terminal:

svn co https://plugins.svn.wordpress.org/your-plugin-name your-plugin-name

This command tells SVN to check out (co) the repository at the specified URL and create a local copy in the directory named your-plugin-name. Replace your-plugin-name with your actual plugin’s name.

After running this command, you’ll have a local copy of your plugin’s repository, complete with its entire version history. This local copy is where you’ll make changes, test your code, and prepare your updates before committing them back to the WordPress.org repository.

3. Authenticate with WordPress.org

Checking out a plugin repository doesn’t need a login, because the repository is public to read. But the moment you try to commit changes, SVN will ask you to authenticate.

Since October 2024, WordPress.org changed how this works. Two-factor authentication (2FA) is now required for all plugin and theme authors. Because 2FA can’t be applied to SVN directly, you now use a separate SVN password instead of your main WordPress.org account password. This password is only for committing code. You can’t use it to log into your account.

Generate your SVN password

1. Log in to WordPress.org and open your profile: https://profiles.wordpress.org/me/profile/edit/
2. Go to the Account & Security tab.
3. Click SVN credentials.
4. Click Generate Password.
5. Click Copy to copy the password to your clipboard.

The password is generated for you, so you can’t set your own. Save it somewhere safe, like a password manager. You can generate a new one at any time, but doing so cancels the old one.

Enter your credentials

The first time you run a command that needs commit access (like svn ci), SVN will prompt you:

Authentication realm: <https://plugins.svn.wordpress.org:443>
Use your WordPress.org login
Password for 'your-username':

Enter your WordPress.org username, then paste the SVN password you just generated. SVN caches your credentials, so you usually only enter them once per machine.

If you’re using a deployment script, like a GitHub Action, you can pass the username and password straight into the commit command:

svn ci -m "Your commit message" --username your-username --password your-svn-password

Important note:

Your WordPress.org username is case-sensitive and can include spaces. Copy it exactly as it appears on your profile.

If you still get an “Authentication Failed” error, make sure you’re listed as a committer on the plugin. Only committers can push changes.

SVN Directory Structure

Your SVN repository will have the following structure:

• /trunk/: Contains the latest development version of your plugin
• /tags/: Stores different released versions of your plugin
• /assets/: Holds plugin assets like screenshots and banners

Basic SVN Workflow

Understanding these fundamental SVN commands will streamline your WordPress plugin development process:

1. Sync Local Copy with Remote Repository

svn up

Synchronizes your local copy with the latest changes from the remote repository.

2. See which files have been modified

svn stat

Displays the status of files in your working copy, showing modified, added, or deleted files.

3. Before committing, review your changes

svn diff

Shows the exact changes made to your files, line by line.

4. Stage New Plugin Files for SVN Commit

svn add trunk/*

Adds all files in the trunk directory to version control. For a more comprehensive approach:

svn status | grep "^\?" | awk '{print $2}' | xargs svn add

This command adds all newly added files in your working copy.

Important note:

In SVN, you don’t need to explicitly “stage” modified files. This is different from Git, where you have to stage (add) both new and modified files before committing.

Modified files are automatically included in the next commit without any additional staging step.

5. Remove Deleted Files

svn st | grep ^! | awk '{print " --force "$2}' | xargs svn rm

Removes files from version control that you’ve deleted locally.

6. Commit Changes

svn ci -m "Your commit message"

Pushes your local changes to the remote repository with a descriptive message.

7. Tag a New Version

svn cp trunk tags/2.0
svn ci -m "Tagging version 2.0"

Creates a new tag for version 2.0 and commits it to the repository.

Conclusion

While SVN might seem old-fashioned compared to Git, it’s a powerful tool that serves its purpose well for WordPress plugin development. By following these guidelines, you’ll be able to manage your plugin effectively and collaborate smoothly with the WordPress.org ecosystem.

Remember, practice makes perfect. The more you use SVN, the more comfortable you’ll become with its workflow and commands.

I value your expertise: share your SVN tips, challenges, or best practices for WordPress plugin development in the comments below to help our community grow and improve together.