Flumes Short User Guide to Subversion
Peter Nordin
January 7, 2014
This guide is primarily meant as an introduction to Subversion for users of the svn accounts
administered by the Division of Fluid and Mechatronic System at Linköping University. It
contains basic usage instructions and suggestions.
Contents
1 What is Subversion
1
2 What do You Need
2.1 On Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 On GNU/Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 On Apple Mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1
1
1
1
3 Using Subversion
3.1 Getting Started . . . . . . . . . . . . . . . . . . . .
3.1.1 Browsing . . . . . . . . . . . . . . . . . . .
3.2 Update, Add and Commit . . . . . . . . . . . . . .
3.3 Moving, Copying and Renaming Files . . . . . . .
3.3.1 Windows and TortoiseSVN . . . . . . . . .
3.3.2 Rename (and Move) . . . . . . . . . . . . .
3.4 Reading the Log, Checking Status and Differences
3.5 Reverting Changes . . . . . . . . . . . . . . . . . .
3.6 Reverse Merging (undo committed changes) . . . .
.
.
.
.
.
.
.
.
.
2
2
2
2
2
2
3
3
3
3
4 Automatic Merging and Conflicts
4.1 Avoiding Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3
4
5 Properties
4
6 Do and Do Not
5
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1
What is Subversion
Subversion is a cross-platform, open-source (free), version control system that will help you
to manage files and directories. It will also keep track of all the changes made to them,
over time. Any changes made to your files can be committed together with a log messages.
Each commit will generate a new revision number. Once a revision has been committed to
subversion it is not possible to remove it. At any time any revision can be retrieved from
subversion. Revisions can also be examined and compared to show exactly what has changed
between two versions of a set of files.
The use of a version control system is greatly recommended in projects that contain many
files and where you want to make sure that you never loose any information. If many people
are going to work with the same set of files a version control system is a must.
2
2.1
What do You Need
On Microsoft Windows
You need to download a subversion client to your computer. We recommend TortoiseSVN
from http://tortoisesvn.tigris.org
If you are using Windows7 then due to a “bug” you may need to deactivate indexing for
your checked out working copies or you may get an incorrect “corrupted files” error when
updating them. You can access the TortoiseSVN commands from the right click context menu.
If you choose to install the command line client, you can also access subversion commands
from the “command prompt” with the same syntax as the Linux client.
2.2
On GNU/Linux
Command line and graphical subversion tools can be installed from your distribution package
repository. In Debian-based distributions you can install subversion with the following command apt-get install subversion. Recommended graphical interfaces are kdesvn (part
of KDE) or rabbitvcs (if you are not using KDE).
2.3
On Apple Mac
This is one way to install subversion, there are others. First download the appropriate Universal Subversion binaries from here: http://www.open.collab.net/downloads/community/.
Then follow the installation instructions. Be sure to read the installer text as it explains
some things you may need to know. If you want a GUI interface there is one called
svnX, see http://code.google.com/p/svnx/. After installing it you must point it to the
folder where you first installed the subversion binaries. This will probably be something like
/opt/subversion/bin. If you want to use these subversion binaries from any folder in your
terminal you must also add something similar to export PATH=/opt/subversion/bin/:$PATH
to the .bash_profile file in your home directory. (Create it if it does not exist (do not forget
the . in the beginning).
1
3
Using Subversion
3.1
Getting Started
The first thing you need to do is to checkout a so called “working copy” from the repository
server. With TortoiseSVN, first create an empty folder, then right click it and select “SVN
Checkout”. The “working copy” can be seen as your own mirror of the files on the server. To
be able to checkout, you must know the path to the repository, its URL. If access rights are
required you will also need a username and a password. NOTE! Do NOT use the import
command as this will do the opposite and commit (send) lots of junk from your current
directory into the repository. You can not undo a commit or import operation.
3.1.1
Browsing
If you have been given a repository path (URL) but only want to look at the contents or
download specific files you can instead browse the repository through your web browser. This
is also handy if you want to find the path to a specific sub folder that you can checkout
instead of the full repository. Some repositories may be very large and you might only be
interested in a sub folder of the repository. You will, however, not be able to commit new
files or changes through the web browser.
3.2
Update, Add and Commit
To update your working copy with the latest changes from the server use the Subversion
command; update. To send in new changes that you have made yourself use the command;
commit. Remember to give a descriptive log message. Before you can commit new files you
will need to add them with the command; add. Your working copy can contain both files
that are under version control and files that are not under version control.
3.3
Moving, Copying and Renaming Files
We do not want duplicate copies of the same files on the server. Any changes you make should
be traceable all the way back to when the original file was added. To move or copy files, use
the built in Subversion commands rather than “left click drag and drop” as you may be used
to. If you “drag and drop” files that are under version control they will loose their version
control system connections and appear as new ordinary files not under version control.
With the command line subversion tools the svn move, svn copy and svn rename commands accomplish these things.
3.3.1
Windows and TortoiseSVN
On Windows using TortoiseSVN you can find the built in Subversion move and copy, “drag and
drop” commands by holding the right mouse button when dragging. Use these instead of the
usual Windows copy and move commands. Note! With new versions of ToroiseSVN you can
also use the ordinary Windows cut and copy commands but you must use the TortoiseSVN
paste command found under the TortoieSVN right-click sub menu.
2
3.3.2
Rename (and Move)
To rename a file use the Subversion command; rename. Instead of creating a new copy of the
file with a new name, a new revision of the file will be added. When you rename or move files
(actually the same thing) using subversion commands no additional space is needed on the
server as the file contents have not changed. When a subversion copy is made, a new branch
of the file is created. The entire version history for the copied file will still be traceable back
to the original file.
3.4
Reading the Log, Checking Status and Differences
To see which files that were changed between different revisions, take a look in the history
log. If you are using a GUI svn client you can usually click on the files indicated to have
changed and select show difference to see the actual changes. (This is especially handy when
working with program source code). You can also issue a svn status command to see what
files in your local working copy that have changed since your last update. In GUI clients this
is usually shown automatically with pretty colours and icons.
3.5
Reverting Changes
Use the revert command to “undo” local changes. Convenient if you accidentally add a lot of
files that were not supposed to be added or if you accidentally made changes to files that were
not supposed to be changed. (You must revert before committing). Revert can be called on
individual files or recursively on directories. Revert will remove non-committed changes that
you have made, be sure to backup your work manually before reverting if you feel uncertain.
3.6
Reverse Merging (undo committed changes)
If you want to “undo” bad changes that were committed you can simply replace the files
manually with an older version and commit. A more correct way is to reverse merge changes
between revisions. On the command line navigate to your working copy and run something
like svn merge -r HEAD:244 . (Do not forget the dot in the end). This will merge the
changes that occurred between revisions 244 and HEAD backwards and restore your working
copy to the state of revision 244. If we assume that HEAD = 245, when you have committed
your reversed changes (at revision 246) then revision 246 should be equal to revision 244. But
since you can never remove data from a repository, the bad revision 245 will still be in the
system. (This is a good thing as you can never loose information).
4
Automatic Merging and Conflicts
When several people are working with the same set of files or even the same file there will be
problems if different changes have been made in the same place. The one who first commits
changes will not have a problem but the next one might. If changes in the same file occur
at different places subversion will in most cases be able to automatically merge the two new
versions of the file. If changes have occurred at the same place or if a file has been renamed
or moved the file will be put into a conflict state.
When a conflict occurs you must do some manual work. You need to look at both versions
of the conflict file and figure out what changes you want to keep. After a conflict has been
3
corrected you must use the svn command resolved on the files in conflict before you can
commit them.
Automatic merging only works on files that are based on plain text, examples are source
code files, some model files or LATEXdocuments. Binary files (like .png images or .pdf files) will
always end up in a conflict state if they have been changed from multiple places within the
same revision. Even though automatic merging works with text based files this feature may
be useless on files that are automatically generated by some programs. Examples are word
processors that store the document in some xml format or model files from certain simulation
programs. These files may be significantly changed every time that they are saved. They
should be treated as if they where binary files, that is, do not rely on automatic merging.
4.1
Avoiding Conflicts
The best way to solve conflicts is to see to it that they never happen. This can be difficult if
several people are working on the same document or files. If everyone knows what to do and
where to do it this type of problems can be avoided. See to it that you update your working
copy often. You should always have a fresh set of files before you begin your work. After
changes have been made, do not forget to commit, if you wait to long someone else might do
similar changes. Before doing major changes to the file structure in a repository, make sure
that every one else working with the files knows this and have time to commit their work
before you begin.
5
Properties
Subversion allows you to “tag” files with special subversion properties that may be useful in
some cases. One example is if you are working with plain text files across platforms. The
svn:eol-style property will make sure that the correct type of line endings are used on
the respective platforms. You can find more information about common properties here,
http://svnbook.red-bean.com/nightly/en/svn.ref.properties.html. If you want your
client to automatically activate these properties on new files when they are added you should
set your auto-props settings in the Subversion client config file. An example is shown below,
where the client have been set to add suitable properties to C++ code project files. Your
case may be different.
[auto-props]
*.cc = svn:eol-style=native;svn:keywords=Id
*.cpp = svn:eol-style=native;svn:keywords=Id
*.h = svn:eol-style=native;svn:keywords=Id
*.hpp = svn:eol-style=native;svn:keywords=Id
*.pro = svn:eol-style=native
*.prf = svn:eol-style=native
*.dox = svn:eol-style=native
*.xml = svn:eol-style=native
*.hmf = svn:eol-style=native
*.txt = svn:eol-style=native
*.tex = svn:eol-style=native
*.bat = svn:eol-style=native;svn:executable;svn:keywords=Id
4
*.sh = svn:eol-style=native;svn:executable;svn:keywords=Id
6
Do and Do Not
Do:
• Use the subversion specific copy, move and rename commands. Really, not only do
you save space on the server but tracing changes will be a lot easier.
• Use svn help or for example svn help update to get hints on some more advanced
usage possibilities of the subversion command line commands. In GUI clients use the
built in help.
Do Not:
• If you are working on files from multiple platforms like Windows and Mac avoid using
file names with special characters like å, ä, and ö. There have been problems reported
when Mac users try to checkout such files created in Windows. The character encoding
does not match so the files are immediately put into a conflict state.
• Avoid adding files that are automatically generated to the repository. These will often change completely and in different ways on different computers. They will often
cause conflicts. Only use version control on important files that you create yourself.
Documents, images, source code and model files are some examples of such files.
• Do not commit very large files like uncompressed movies or log-data. Lots of large data
will make checkouts and updates slow. Also as this is a version control tool EVERY
file and change you commit will be saved. Revisions can not be removed which means
that the repository will always grow in size. If you have large data that you need to
work with frequently it is OK, but uncompressed movies and such files should never
be added. If your files are several hundred megabytes (or even gigabytes) in size, you
should try to store and distribute them in some other way.
5