Go to page:

Search:   Help

Developers' side bar

Selected categories


Shared groups



<< | Page list | >>

Developing LyX using Subversion. Various tips, recommendations and suggestions for a better workflow.

Introduction and background

This page was created after Richard1 asked for suggestions on how to work with branches more efficiently, or more specifically: How to merge the work back into trunk.

A lot of this information is of course available in the SVN book. The purpose of this page is not to duplicate that information, but to give concrete and applicable examples for working with the LyX repository.

In addition, the recommendations will also relate to a workflow in the LyX development when using Subversion.

Some "simple" Subversion commands and tasks

The following commands assume you have commit permissions to the repository, i.e. in practice an account on the server (svn.lyx.org aka aussie.lyx.org). Ideally the commands should be useful as copy'n'paste, i.e. actually useful, so please use real URIs.

Use svn help for help via the command line, or read the SVN Book (see the links at the end).

  • Checking out working copies.
    • Check out trunk to a directory called lyx-devel/.
    svn co svn://svn.lyx.org/lyx/lyx-devel/trunk lyx-devel
You an use TRAC to browse the repository and find the desired path this way.
  • Check out LyX release 1.5.x (BRANCH_1_5_X) to a directory called lyx-1.5.x
svn co svn://svn.lyx.org/lyx/lyx-devel/branches/BRANCH_1_5_X lyx-1.5.x
  • Check out Lars' XML a branch to a directory called lyx-XML
svn co svn://svn.lyx.org/lyx/lyx-devel/branches/personal/larsbj/xml lyx-XML
  • Update your your working copy
    svn update
  • Revert to a specific version
    svn up -r 19440
    This is a tricky one, as it seems you ought to do @@svn revert...@, but that is wrong.
  • The command to show the log of another branch
    svn log svn://svn.lyx.org/lyx/lyx-devel/branches/personal/larsbj/xml
    There are two very useful options here: --limit n, which will print only n log messages, and --stop-on-copy, which will output only log messages particular to this branch and will not, in particular, output messages from before the branch was created.
    There seems to be a bug here, or something of the sort. If /cvs/mybranch is a working copy of svn://svn.lyx.org/lyx/lyx-devel/trunk, then you'd expect that svn log /cvs/mybranch/ and svn log svn://svn.lyx.org/lyx/lyx-devel/trunk would give the same results, but they do not (at least not on one person's system). The latter is the command you want.
  • Apply a change made in trunk to a branch
    When fixing bugs, in particular, you often want to apply a change made and committed in trunk to a local copy of the current branch, so that the change can be applied to the branch as well. Here is how to do this. Suppose you have just committed a fix for an evil bug to the trunk as revision 19876. You now want to apply this same change to 1.5.2svn, a copy of which you have checked out as @/cvs/lyx-devel/branches/BRANCH_1_5_x/@@. Here is the command:
    svn merge -c19876 svn://svn.lyx.org/lyx/lyx-devel/trunk/ /cvs/lyx-devel/branches/BRANCH_1_5_x/
    The -c option tells svn merge to apply the change made at revison 19876---the one you just committed. Of course, the patch may not apply cleanly, and you may have some work to do, but this gets you started without cutting and pasting.
  • Feel free to add more simple/convenient examples

Tips for working with branches

You want to develop a new feature in a branch.

Overall recommendations:

  • Use one branch for a single purpose
  • Update your branch with respect to trunk frequently
  • Backport cosmetic changes first - that'll simplify your later diffs.

Creating branches — One branch, one purpose

Use one branch for a single purpose in order to later simplify a merge with trunk.

Location of branches

Personal branches for LyX development should be located as follows:


that for Lars' XML branch translates to the follwing URI:


It can be browsed through the link LyXVCS:lyx-devel/branches/personal/larsbj. 2

Creating a branch

There are several ways to create a branch. Below is a way to create a branch without having to check out anything locally:

svn copy svn://svn.lyx.org/lyx/lyx-devel/trunk \ svn://svn.lyx.org/lyx/lyx-devel/branches/personal/user/branch \ -m "Creating a private branch for XML development based on /lyx-devel/trunk."

Update your branch from trunk

Here is how you can update your branch with respect to trunk.

First, commit whatever changes you've made locally. Then, if there's a mistake, you can always revert to that revision.

It's a bit of a weakness of Subversion that you need to know when your branch was last updated with respect to trunk. Subversion has no way of keeping such information for you. It's a good idea to write this down, but you can find it by examining your commit logs: You should always commit as soon as you've merged from trunk and gotten things working again. That said, use:

svn log svn://svn.lyx.org/lyx/lyx-devel/branches/personal/user/branch

to examine your commit logs. If you make a point of starting all and only the commits following merges with the word "Sync", then try this:

svn log --limit 1 svn://svn.lyx.org/lyx/lyx-devel/branches/personal/user/branch | \ grep -B2 Sync

With a little more cleverness, you could actually extract the revision number:

svn log --limit 1 svn://svn.lyx.org/lyx/lyx-devel/branches/personal/user/branch | \ grep -B2 Sync | head -n1 | cut -d' ' -f1 | | sed -e's/r\(.*\)/\1/'

See below for something to do with it.

So let's say you last merged from trunk at revision 19245. Then you can merge new changes since then as follows:

svn merge [--dry-run] -r 19245:HEAD svn://svn.lyx.org/lyx/lyx-devel/trunk

where this command is run from your own local copy of your branch. It's a good idea to use the --dry-run argument the first time before you do this for real.

So now try this, if you have bash (though it should work with trivial modifications with other shells):

#!/bin/bash REV=`svn log --limit 1 svn://svn.lyx.org/lyx/lyx-devel/branches/personal/user/branch | \ grep -B2 Sync | head -n1 | cut -d' ' -f1 | | sed -e's/r\(.*\)/\1/'`; svn merge -r $REV:HEAD svn://svn.lyx.org/lyx/lyx-devel/trunk

We wouldn't recommend using it in that form, but you get the idea.

See Ch. 4, sec 3 and later sections in the SVN book for more on merging branches.

Comparing two branches

Here is how you can compare two branches (do a diff) between for instance the trunk and 1.5-branch.

svn diff svn://svn.lyx.org/lyx/lyx-devel/trunk \ svn://svn.lyx.org/lyx/lyx-devel/branches/BRANCH_1_5_X

If you want to compare at a particular revision, you can add the revision number to the end of the name of the working copy, thus:

svn diff svn://svn.lyx.org/lyx/lyx-devel/trunk@19251 \ svn://svn.lyx.org/lyx/lyx-devel/branches/BRANCH_1_5_X@19278

You can also refer to a local copy:

svn diff svn://svn.lyx.org/lyx/lyx-devel/trunk \ /cvs/lyx-devel/branches/BRANCH_1_5_X

And any path is acceptable, including one that specifies a particular file:

svn diff svn://svn.lyx.org/lyx/lyx-devel/trunk/src/callback.cpp \ svn://svn.lyx.org/lyx/lyx-devel/branches/BRANCH_1_5_X/src/callback.cpp

Backporting changes

Tips on how to backport changes from a branch to trunk. On the overall, you should proceed as follows:

  1. First backport cosmetic and simple/trivial changes to be sent as a patch to the list. This will simplify later patches. (This may of course also be separated into two changes/patches).
  2. If necessary, split up the remaining changes into logical and managable sets of changes and backport them separately
Backporting a set of changes
  1. Update your working copy of the branch
  2. Update your working copy of the trunk
  3. Compare your working copy to trunk and look at the difference
    Then there at least two ways to proceed, depending on taste
  • Alternative A:
    1. Manually go through the changes and apply them to your working copy of the trunk.
    2. Create a patch for the changes you did in your working copy of trunk
    3. Submit the patch of the changes for review/approval
  • Alternative B:
    1. Create a patch from the diff between your branch and trunk
    2. Edit the patch to remove undesired changes (chunks)
    3. Apply the edited patch to your working copy of trunk
    4. Create a patch for the chages you did inyour working copy of trunk
    5. Submit the patch of the changes for review/approval

There are probably tools out there that can help with this process.

Insert references to such tools.
Merging a whole branch to another

You want to merge your branch to a working copy of trunk. How do you do it?

  • Find out the base revision of your branch. Use e.g.
svn log --stop-on-copy \ svn://svn.lyx.org/lyx/lyx-devel/branches/personal/larsbj/xml
  • Update and check the revision of your working copy of trunk
    cd lyx-devel/trunk; svn update
  • Merge. The example assumes the base of the branch is 19477, and that the revision of trunk is 19500. You must be in the working copy of trunk for this example to work.
svn merge -r 19477:19500 \ svn://svn.lyx.org/lyx/lyx-devel/branches/personal/larsbj/xml

The result is a locally changed working copy of trunk that now contains the work from the branch. Use svn status to see what's changed.

Deleting branch

One example for deleting advsearch branch:

 svn delete svn://sanda@svn.lyx.org/lyx/lyx-devel/branches/advsearch   

Comments related to working with branches

Please gather your comments about how to work with branches in this section.

Win <-> Unix CR-LF

In order to have correct EOLNs you should use:

svn propset svn:eol-style native FILE

when adding file to the project tree.

Setting executable flags

svn propset svn:executable ON SCRIPT_FILE

Setting locking property

svn propset svn:needs-lock ON FILE

Related links


Category: Development, Subversion, Tips


1 There was also a ruccus with Abdel. (↑)

2 The prefix LyXVCS: is a prefix for linking to the repository browser. (↑)

Edit - History - Print - Recent Changes - All Recent Changes - Search
Page last modified on 2011-04-15 18:24 CEST