• Browse GIT
• View
• Edit
• Upload
• History
• Print

Subversion

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

1.  Introduction and background

This page was created after Richard¹ 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.

2.  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

• Check out Lars' XML a branch to a directory called 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

3.  Tips for working with branches

Purpose

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.

3.1  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:

lyx-devel/branches/personal/<user>/<branch-name>

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

svn://svn.lyx.org/lyx/lyx-devel/branches/personal/larsbj/xml

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

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:

3.2  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:

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:

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

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:

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):

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.

3.3  Comparing two branches

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

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:

You can also refer to a local copy:

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

3.4  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.

• 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.

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.

3.5  Deleting branch

One example for deleting advsearch branch:

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

3.6  Comments related to working with branches

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

4.  Win <-> Unix CR-LF

In order to have correct EOLNs you should use:

when adding file to the project tree.

5.  Setting executable flags

6.  Setting locking property

7.  Related links

• The Svnbook
  • Svnbook, ch-3, sec 5.3.1 - about the command 'svn status'. This chapter also discusses many other commands (e.g. diff, copy, revert etc).
  • Chapter 4. Branching and Merging - Table of Contents. What's Branch.
    • Using Branches.
    And the sections after this...

8.  Categories

Category: Development, Subversion, Tips

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

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