Subversion Repositories SvarDOS

                                SVN QUICKSTART

                [authored by Mateusz Viste, the 29th June 2023]

=== INTRO =====================================================================

This document is aimed at people that are committing changes to the SvarDOS

svn repository: developers, packagers, writers, translators...

If you are reading this, then you probably received a write access to the

SvarDOS svn server at svn.svardos.org, ie. a login and password.

Subversion isn't hugely popular these days, hence people are less and less

comfortable with it. But worry not - it's extremely straightforward!

This is obviously not meant to be a complete manual of svn. Here you will learn

the few most basic operations that will allow you to interact with svn right

away. In case of more in-depth details about Subversion usage I recommend

consulting the excellent SVN book at https://svnbook.red-bean.com/.

=== REPOSITORY CHECKOUT =======================================================

This is one time action that you need to perform so your svn client pulls the

current state of the SvarDOS repository to your disk. It's called a "checkout":

  svn co svn://your.username@svn.svardos.org/svardos

This will create a "svardos" directory on your disk. All further actions will

be always performed from within this directory.

=== PERIODIC UPDATES ==========================================================

The repository changes with time, so you need to make sure that your local copy

is always up to date. To do so, you only need to execute a single command from

time to time. We call it an "update":

  svn up

=== CREATE A NEW DIRECTORY ====================================================

If you need to create a new subdirectory somewhere in the repo, you can either

ask your svn client to do it, or do it yourself and then ask your svn client to

track it.

Option 1:

  svn mkdir newdir

Option 2:

  mkdir newdir

  svn add newdir

=== ADD A NEW FILE TO THE REPOSITORY ==========================================

If you creates a new file (new translation, new package, new code file...), you

need to tell svn about it so it starts to version it:

  svn add newfile.txt

=== DELETE A FILE OR DIRECTORY ================================================

Deleting a file or directory via svn is as simple as this:

  svn del file_to_dele.txt

  svn del dir_to_delete

And of course, you need to commit the changes to apply them on the server.

=== REVIEWING YOUR CHANGES BEFORE COMMIT ======================================

You have done some changes on your local data, and are ready to push them to

the server? Thath's great, but I encourage you to review your changes one last

time, asking svn to list them.

1. Display the list of changed files or directories:

  svn st

2. Display the difference between your local files and the server's content:

  svn diff

Both these operations will show you the state compared to the last known

content of the server. To make sure nothing changed on the server in the mean

time, you should update your local copy (svn up) beforehand.

=== UNDOING (REVERTING) LOCAL CHANGES =========================================

You made some huge mistake and would like to erase your local changes to revert

back to the last known server's state? Easy:

  svn revert file_or_dir_to_revert

It is worth mentionning that this works even if you deleted your local copy of

the file or dir.

=== COMMIT ====================================================================

Finally, you made your changes, reviewed them, made sure your local files are

up to date, and are ready to push things to the server. Awesome. To push all

your changes at once, do a general commit:

  svn commit -m "short description of the changes"

If you prefer to push your changed files in separate commits for a better

visibility, then that' s no problem either:

  svn commit -m "fixed bug #123" changed_file.c

  svn commit -m "improved polish translations" pl.txt

  svn commit -m "updated FDISK to ver 1.3.7" fdisk-1.3.7.svp fdisk-1.3.7.zip

=== WHY SVN? ==================================================================

Nowadays most project rely on git for their versioning. Many people think

that's because of some technical superiority of git. I think that's rather a

bandwagon trend.

Of course I have nothing against git. It is a very impressive technology and an

outstanding solution to the specific problem it was designed for: enabling

collaboration of huge, unorganized teams on a complex code base while having no

centralized authority. But when it comes to more limited projects, it is my

opinion that git is an unnecessary complication that presents no added value

over svn, while having a number of downsides:

 - lack of a centrally managed repository,

 - lack of monotonically increasing revisions,

 - non-obvious usage,

 - poor storage of binary files,

 - inefficient client-side storage (stores the entire history)

 - ...

Subversion, on the other hand, is simpler due to its centralized nature.

Syncing (updating) local files is both faster and leaner than with git, because

svn cares only about the latest available revision, it does not keep the entire

project's history on the client side. In a word - it's simpler, and I am always

in favor of technical simplicity as long as it does not come with significant

limitations.

======================================================================= EOF ===