Flumes Short User Guide to Subversion

Transcription

1 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 On Microsoft Windows On GNU/Linux On Apple Mac Using Subversion Getting Started Browsing Update, Add and Commit Moving, Copying and Renaming Files Windows and TortoiseSVN Rename (and Move) Reading the Log, Checking Status and Differences Reverting Changes Reverse Merging (undo committed changes) Automatic Merging and Conflicts Avoiding Conflicts Properties 4 6 Do and Do Not 5

2 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 What do You Need 2.1 On Microsoft Windows You need to download a subversion client to your computer. We recommend TortoiseSVN from 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: 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 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 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 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 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

4 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

5 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 L A TEXdocuments. 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, 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

6 *.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