We’ll describe here some of the basics about using subversion: starting out, changing things, and tagging releases. For more comprehensive documentation, see The SVN Book.
First, some terminology
If you’re new to subversion, you’ll need to know what a few words mean, so let’s go over how subversion behaves to introduce some terms.
All your files will be centrally stored in the repository on our servers. From that repository, anyone can check out a copy of your plugin files onto their local machine, but, as a plugin author, only you have tho authority to check in. That means you can make changes to the files, add new files, and delete files on your local machine and upload those changes back to the central server. It’s this process of checking in that updates both the files in the repository and also the information displayed in the WordPress.org plugin directory.
Subversion keeps track of all these changes so that you can go back and look at old versions or revisions later if you ever need to. In addition to remembering each individual revision, you can tell subversion to tag certain revisions of the repository for easy reference. Tags are great for labelling different releases of your plugin.
Words are great, but how do I actually use the darn thing?
Let’s describe a few basic tasks you might want to accomplish.
Task 1: Starting from scratch with your brand new plugin repository
All you want to do is add the plugin files you already have to your new repository.
To do that you’ll need to
- Check out the blank repository.
- Add your files to the
trunk/directory of your local copy of the repository. - Check in those files back to the central repository.
$ mkdir my-local-dir
# Check out the repository
$ 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.
# As you can see, subversion has added ( "A" for "add" )
# all of the directories from the central repository to
# your local copy.
# Copy the plugin files to the local copy.
# Put everything in the trunk/ directory for now.
$ cd my-local-dir/
my-local-dir/$ cp ~/my-plugin.php trunk/my-plugin.php
my-local-dir/$ cp ~/readme.txt trunk/readme.txt
# Let subversion know you want to add those new files
# back into the central repository.
my-local-dir/$ svn add trunk/*
> A trunk/my-plugin.php
> A trunk/readme.txt
# Now check in the changes back to the central repository.
# Give a message to the check in.
my-local-dir/$ svn ci -m 'Adding first version of my plugin'
> Adding trunk/my-plugin.php
> Adding trunk/readme.txt
> Transmitting file data .
> Committed revision 11326.
# All done!```
### Task 2: Editing a file that is already in the repository
We’ll assume you’ve already got your plugin repository filled with the needed files ([Task 1](#task-1)). Now suppose you need to edit one of the files to improve the plugin.
To do that you’ll need to
1. Make sure your copy of the repository is up to date.
2. Edit the file.
3. Double check your changes.
4. Check in your changes.
```# cd into your local copy of the repository and
# make sure it's up to date
$ cd my-local-dir/
my-local-dir/$ svn up
> At revision 11326.
# Good: all up to date. If there had been changes in the
# central repository, they would have been downloaded and
# merged into your local copy.
# Edit the file that needs changing. I use nano.
# No need for editor wars; use whatever you like.
my-local-dir/$ nano trunk/my-plugin.php
# ... edit ... edit ... make typo ... edit
# ... fix typo ... edit ... all done.
# You can check and see what's different between your
# local copy and the central repository.
# First we check the status of the local copy.
my-local-dir/$ svn stat
> M trunk/my-plugin.php
# This tells us that our local trunk/my-plugin.php
# is different from the copy we downloaded from the
# central repository ( "M" for "modified" ).
# Let's see what exactly has changed in that file,
# so we can check it over and make sure things look right.
my-local-dir/$ svn diff
> * What comes out is essentially the result of a
* standard `diff -u` between your local copy and the
* original copy you downloaded.
# Looks good. Let's check in those changes to the
# central repository.
my-local-dir/$ svn ci -m "fancy new feature: now you can foo *and* bar at the same time"
> Sending trunk/my-plugin.php
> Transmitting file data .
> Committed revision 11327.
# All done!```
### Task 3: “Tagging” a new version
Each time you make a formal release of your plugin, you should tag a copy of that release’s code. This lets your users easily grab the latest (or an older) version, it lets you keep track of changes more easily, and lets the WordPress.org Plugin Directory know what version of your plugin it should tell people to download. To do that you’ll need to **remember to update** the `Stable Tag` field in [`trunk/readme.txt`](https://wordpress.org/plugins/about/readme.txt) beforehand! Then you’ll
1. Copy your code to a sub-directory in the `tags/` directory. For the sake of the WordPress.org plugin browser, the new sub-directory should always look like a version number. `2.0.1.3` is good. `Cool hotness tag` is bad.
2. Check in that new sub-directory.
```# You've just checked in the latest and greatest updates
# to your plugin, let's tag it with a version number, 2.0.
# To do that, copy the files from your trunk/ directory to
# a new directory in tags/.
# Make sure to use `svn cp` instead of the regular `cp`.```
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.
# All done!
**This archived WordPress Wiki is pulled from good ol’ archive.org**
