/ howto / svn
How To Deal With Subversion
Subversion is the software that manages the Gambas source code repository on http://sourceforge.net.

A repository is exactly like a file system, but a file system that keeps all modifications.

## Getting a write access to the Gambas repository

Everybody can make a copy of the repository on his hard disk by using the following command:

    $ svn checkout https://gambas.svn.sourceforge.net/svnroot/gambas/2.0/trunk/

But if you want to do development or translations for Gambas, then you need a write access to the repository.

To get that, just create a user account on sourceforge.net, and ask me to grant a write access to the user you just have created.

## How does it work?

Each time anything is changed in the repository, the revision number is incremented, and a revision log is attached to it. The revision log is edited by the person doing the modification.

All is done with the `svn` command.

- `svn checkout` makes a copy of the repository on your hardisk, and adds many hidden `.svn` directories everywhere in it to track the changes.

- `svn commit` sends all your modifications back to the server, asks for the revision log, and increments the revision number. Each commit has its own revision number and revision log.

- `svn update`, upgrades your local copy of the repository to the last version.

Someone may have modify some things between the time you checked out and the time you committed. So before doing a `svn commit`, you should do a `svn update`.

### Writing revision log

When you commit, you must specify the editor used for editing the revision log in the `$EDITOR` environment variable. For example:

    $ EDITOR=gedit svn commit

| Note that you cannot modify a revision log after the commit. It seems that sourceforge has disabled this feature. So, be careful!

### Revision log format

I want to have a standard way to write commit messages, so that ChangeLog can be almost automatically generated.

The format is the following:

- A ChangeLog slot, between '`[`' & '`]`'
- A ChangeLog modification: a '`*`', a space, the word '`BUG`', '`NEW`' or '`OPT`', a colon, a space, and the text.

'`BUG`' is for a fix, '`NEW`' for a new feature, translation, or updated ones, and '`OPT`' is for an optimization.

Slots are the name of the component in uppercase, or one of the following:

- `[INTERPRETER]`
- `[COMPILER]`
- `[ARCHIVER]`
- `[INFORMER]`
- `[DEVELOPMENT ENVIRONMENT]`
- `[DATABASE MANAGER]`
- `[CONFIGURATION]`
- `[WIKI CGI SCRIPT]`

All lines must be lower or equal than 76 characters.

If a changelog modification is more than one line, you must use a two space indent.

Void lines are ignored.

All other lines won't go into the changelog.

### Examples

    I did this thing, and this won't go into the changelog.

    [GB.QT]
    * BUG: I fixed this bug.
    * NEW: I made this very long modification....
      and it takes more than one line to write it.

    This won't go into the chanlog too.

    [GB.SDL]
    * BUG: What an awful bug!

    [GB.GTK]
    * NEW: I finally finished the component :-)

Please follow this scheme. It would be cool...

### Commit mailing-list

There is a mailing-list that gets a mail each time somebody (usually me) commits a new revision. So this way you always know if you have the last revision on your hardisk or not.

To subscribe to this mailing-list, go to the mailing-list page on the web site.

### State of your repository copy

To get the state of your repository copy, run the `svn status` command.

Each state is described with one or more letter:

- `?` is a file not managed by subversion.
- `M` is a file you have modified.
- `C` is a file in conflict.
- `G` is a file in conflict that was automatically solved by the `svn` command.
- `A` is a newly added file or directory.
- `D` is a deleted file or directory.
- ... and so on.

See above for more information about conflicts.

## Caveats

### No automatic project structure tracking

You must tell subversion if you add, delete, rename or move a file. You do that with the commands:

- `svn add` to add a file you have already created.

- `svn del` to remove a file.

- `svn move` to rename or move a file.

| Forgetting to use `svn add` is a common mistake. I know what I'm talking about :-)

### Conflicts

Somebody can modify a file in the repository, while you have modified the same file on your hardisk. This is a conflict, and `svn` will tell you when running `svn update`, or the `svn status` command.

Each time there is conflict, `svn` tries to solve it automatically, by merging your own changes with the changes made by other people.

If the merge succeed, your will get a file with a 'G' state character.

If the merge didn't succeed, your will get a file with a 'C' state character. Then you will have to solve the conflict by hand:

- You must edit the file yourself to merge the changes. `svn` has modified the file so that you see your own changes and the other changes side by side.
- Or you can use one of the copy automatically made by subversion. You get one for the last version, and one for the current version of your local repository. Their name are the name of the original file followed by a dot, the letter 'r' and the revision number. Just replace the original file by the copy.

Once done, you will tell `svn` that the conflict is solved by running the `svn resolved` command on the file in conflict.

## Is there any risk?

Normally there is no risk, as everything is archived, and so you can always go back in time.

Moreover, if you work on a Gambas project inside the repository, the development environment can deal with all `svn` command for you. Go to the versioning tab in the project property dialog, and you will find buttons that allow you to update the project, commit it, and cancel your modifications.

If you have made something weird, you can use the `svn revert` command. It will revert you local copy to the state of the last checkout or update.