Using Subversion to track the latest TWiki developments
If you wish to use the latest development versions of TWiki, you can use Subversion
to keep up to date.
What is Subversion?
Subversion is a revision control system. It records all the source code, and tracks changes to that source code.
It can be downloaded from http://subversion.tigris.org/
. A Windows shell extension client is available at http://tortoisesvn.tigris.org/
, and a cross-platform GUI at http://rapidsvn.tigris.org/
. There is also a book about Subversion usage online at http://svnbook.red-bean.com/
See Installing Subversion Client
How does TWiki use Subversion?
The TWiki project has a subversion server at http://svn.twiki.org/svn/
that we use to store and track changes to the TWiki source code, and the source code of many extensions. You don't have
to use subversion to contribute to TWiki, but you'd have to have a pretty strong reason not to.
is used to check in all bug fixes and new code targeted at the next
release. It is a requirement
that the code on the trunk always works
, as we use it to run the bugs server at http://develop.twiki.org/~twiki4/cgi-bin/view
, and most developers rely on it always working for their development environments. So you have to take great care checking code into the trunk.
Due to the nature of development code, major bugs or issues will occasionally be encountered in this code.
When a TWiki release is made, then release branches are created to track minor fixes and security fixes to that code, so that the trunk can move ahead without getting dragged down by old releases. Developers can also create other branches in the
area if they want to try out new ideas.
The code checked into the trunk is used to drive a TWiki at http://develop.twiki.org/~twiki4/cgi-bin/view
, which is used to serve the bugs database. This checkout area is kept up to date by cron job that runs every 10 minutes
. In the best case, the person doing the checkin will be able to almost immediately check the correct functioning of their checkin.
The trunk is also used for TWiki extensions, which sometimes follow the same release cycle as the core code, but often don't. Extension developers can use the trunk without fear of breaking the bugs database, as long as they:
- Don't check into any of the 'standard' plugins that are installed by default with a TWiki release (see
- Check only into Extension named subdirectories (e.g. MyNewPlugin)
How to check out the trunk
To check out the
core and all =extensions=
svn co http://svn.twiki.org/svn/twiki/trunk .
If you leave out the "." at the end of the
svn co command, it will create a directory named
trunk for you.
This will check out everything
on the trunk - including every extension that has ever been checked in. if you don't want this, and only want to check out a subset of the bits you need, see Checking Out a Subset
for practical advice on using a SVN
checkout as a live install.
if you work on extensions.
How to check out a release branch
There is a branch for each release. There may be other developer branches as well, depending on what is going on.
for the branches. Shipping releases are currently in branches labelled TWikiReleaseNNxNN
, i.e., the shipping code for release 4.1.x is in branch TWikiRelease04x01
. Note that pre-4.2.0, the branch tags were changed to PatchNNxNN
The list of tags can be found at http://svn.twiki.org/svn/twiki/tags/
How to check in
The trunk has "trigger scripts" on it that enforce the following rules:
- All checkins must have a comment
- Checkin comments must list all the Item numbers in Bugs web that document the reason for the change
- Items must be open at the time of checkin (be in Open, Actioning or Waiting for Feedback states)
svn commit -m "Item4815: Corrected inability to open hatch Item4900: Closed hatch to shut out freezing water"
This is to make sure that we have traceability of all changes. These comments are used to update the linkage between items in the Bugs web and checkins in Subversion, so you should try hard to make sure they are accurate and complete.
Branches don't have trigger scripts, so there is no constraint on what message you use when you check in.
If you have been given write access to the repository, you should use the same login and password as your twiki.org WikiName
Even if you can't check in, you can still contribute. Make your changes in your checkout area, and then cd to the root directory of the checkout area and:
svn diff > mypatch.diff
Attach the file
to the relevant topic in Bugs
web (there should be one topic for each change) and ask someone with checkin rights to merge it.
Please ensure the TWikiUnitTests
are run if possible, and always run through the tests
in the TestCases
web in your checkout area.
Check-ins are automatically mailed to the twiki-dev mailing list. See twiki-dev@listsPLEASENOSPAM.sourceforge.net
An RSS feed at http://develop.twiki.org/~twiki4/pub/svn2rss.xml
is also generated on SVN
Scratch area in SVN
is an area for Developers to try out ideas, either a temporary branch, or new twiki related ideas. Anyone with checkin access can create new branches.
To create a new branch of the core code (derived from the trunk) under scratch,
svn copy http://svn.twiki.org/svn/twiki/trunk/core http://svn.twiki.org/svn/twiki/scratch/NewBranchName
For doing the copy, you will be asked for a commit message. You should include an Item number from the Bugs web e.g.
Item90210: Branch for doing performance experiments.
Then go back to checking out a branch, substituting the URL of the new branch.
Checking Out a Subset
The trunk checkout instructions above will check out the TWiki core and every extension. Often you will want to check out just a subset of the code specific to what you are working on or testing. This can save an awful lot of disc space, as well as making subversion commands much faster and more manageable.
The best way to do this is to create a root directory for all your TWiki work. For example, "~/httpdocs/twiki". Then check out the core from the trunk (or whatever release banch you are working on):
svn co http://svn.twiki.org/svn/twiki/trunk/core core
This will checkout the core to the
subdirectory. Now you can checkout the subset of extensions you want to have available:
svn co http://svn.twiki.org/svn/twiki/trunk/TWikiUserMappingContrib TWikiUserMappingContrib
svn co http://svn.twiki.org/svn/twiki/trunk/CommentPlugin CommentPlugin
svn co http://svn.twiki.org/svn/twiki/trunk/EditRowPlugin EditRowPlugin
(note: if you intend to build a TWiki release, you will need to checkout all the extensions listed in
Now you can use
to soft-link (Linux/BSD etc) or copy (Windows) the extensions into the core. For example:
perl pseudo-install.pl default
(some day someone will write a script to do all this in one step. Some day....)
See also MergingInSubversion
Subversion already has rich FAQs, and Google is your friend, so this FAQ is restricted to questions that relate to the TWiki project's specific use of subversion.
- Do we have something like ViewCVS or even better a SvnPlugin to access the SVN repository? -- StephaneLenclud - 17 Sep 2006
- No - the svn.twiki.org server is running a rather 'secure' version of CentOS, and all the existing svn repository browsers require alot of configuration and mangement. Ideally, we could do with a set of TWiki based tools that give that sort of version browsing on anything in a supported TWikiStore (and then the SubversionStore needs completing)
- How do I change my local SVN installation to point to the new MAIN branch? Use this command:
Note: the switch may cause you to lose some changes
svn diff > ../BackupChanges.diff
svn switch http://svn.twiki.org/svn/twiki/trunk .
NOTE the little dot at the end. For more details check the SVN
online manual: http://svnbook.red-bean.com/en/1.2/svn-book.html#svn.ref.svn.c.switch
I have a subversion based install running the main branch. If I was to commit a new plugin, where would I run svn commit from? The twiki root, or from /twikiplugins, or even /twikiplugins/NewPlugin?
Just want to check as I have made changes to TWikiUsers
, and obviously they shouldn't be committed.
- 04 May 2007
You can do both: either
to the directory where your changes are located, or from the TWiki root, if you give the path what should be committed. So, the following example works:
$ cd twikiplugins/NewPlugin
$ svn commit -m 'Item007: Track down Blofeld'
...as does the following (from TWiki root):
$ svn commit -m 'Item007: Track down Blofeld' twikiplugins/NewPlugin
Neither will commit anything outside of
. By the way: I think that every TWiki developer has committed "too much" at least once in his career. As an additional safeguard I usually run
with the same path parameter before
to check what will be transferred.
- 04 May 2007
before checking in.
- 04 May 2007
Thanks for you help. For a new plugin, I found
to be better, as it only lists the modified files, not each added line.
- 08 May 2007
Hm... it seems that the RSS feed is broken again (last listed revision is #14059 from 2007-06-08, and the body of all entries contain a link to the root
directory of current revision #16305 as of this writing)
- 28 Jan 2008
How can I checkout the core from a tag or branch? I can't find the
directory as in trunk, but still all plugins and extensions are in the directory. Seems this is not up to date: "_Then check out the core from the trunk (or whatever release branch you are working on)_"
I would like to checkout TWiki v4.2 from svn and have the possibility to make a svn switch to the following versions.
- 25 Apr 2008