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.
Let's describe a few basic tasks you might want to accomplish.
All you want to do is add the plugin files you already have to your new repository.
To do that you'll need to
trunk/directory of your local copy of the repository.
# Create a local directory on your machine to house # a copy of the repository. $ mkdir my-local-dir # Check out the repository $ svn co http://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!
We'll assume you've already got your plugin repository filled with the needed files (Task 1). Now suppose you need to edit one of the files to improve the plugin.
To do that you'll need to
# 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!
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
tags/directory. For the sake of the WordPress.org plugin browser, the new subdirectory should always look like a version number.
Cool hotness tagis bad.
# 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!