If you are participating in a development project that is using Subversion for version control, you will need to use Subversion to access and change project source files. You must have a Subversion client installed on your local machine like Tortoise SVN for Windows or Sourcetree for Mac.
Getting a local working copy for your project
To get a «working copy» of the latest source files, you must check out the source files, a process that copies the files onto your system from the repository. In your shell or terminal client, type:
svn checkout https://(projectname).(domain)/svn/(projectname)/(DIR) (projectname) --username [type-user-name-here] --revision (-r) REV, --quiet (-q), --non-recursive (-N), --password PASS, --no-auth-cache, --non-interactive, --config-dir DIRWorking with files in the Subversion repository
Once you have checked out a local copy of the project repository, you can edit the existing files, create new files and directories, and delete files locally. Any changes you make affect only your local copies of the project files until you commit your changes back to the Subversion repository.
Adding files/directories from your working copy to the repository
You can add a new file to the repository after you have first created and edited it in your working directory or add a directory with or without its contents type:
svn add FILENAME/DIR --targets FILENAME, --non-recursive (-N), --quiet (-q), --config-dir arg, --auto-props, --no-auto-propsThis will add files/directories to your working copy and schedule them for addition to the repository. They will be uploaded and added to the repository on your next commit. If you add something and change your mind before committing, you can unschedule the addition using:
svn revertViewing the content of specific files with revision and author information
You can view the author and revision information in-line for the specified files by typing
svn blame FILENAME --revision (-r) REV, --username USER, --password PASS, --no-auth-cache, --non-interactive, --config-dir DIREach line of text is annotated at the beginning with the author (username) and the revision number for the last change to that line.
Viewing the content of specific files
At times, your working copy may be obsolete as compared to the repository or you may have modified your local working copy. In such cases, you will want to see the differences in the content of a specific file before you commit your changes or decide to edit your working copy.
svn cat FILENAME --revision (-r) REV, --username USER, --password PASS, --no-auth-cache, --non-interactive, --config-dir DIRThis command will automatically fetch the HEAD revision from the repository. This subcommand is mainly used to retrieve a file as it existed in an older revision number and display it on your screen.
Cleaning up the working copy
Sometimes, you may get a «working copy locked» error. To remove the locks and recursively clean up the working copy, use:
svn cleanup --diff3-cmd CMD, --config-dir DIRCopying file or directory in a working copy or in the repository
Your project may require you to make use of legacy documents. For example, you may want to use an already existing HTML file and use its code as a reference to maintain the look and feel of the product while creating fresh content. Instead of creating a file from scratch, you can simply copy this file using svn copy, save it under a different name and change the content. You can copy a file from the repository to your local working copy or vice versa. You can also copy files from within your local working copy. Subversion does not support cross repository copying.
svn copy --message (-m) TEXT, --file (-F) FILE, --revision (-r) REV, --quiet (-q), --username USER, --password PASS, --no-auth-cache, --non-interactive, --force-log, --editor-cmd EDITOR, --encoding ENC, --config-dir DIRDeleting a file or a directory from your local working copy
You may want to delete unwanted files from your local working copy. The actual deletion of the file in the repository takes place only when you commit.
svn delete --force, --force-log, --message (-m) TEXT, --file (-F) FILE, --quiet (-q), --targets FILENAME, --username USER, --password PASS, --no-auth-cache, --non-interactive, --editor-cmd EDITOR, --encoding ENC, --config-dir DIRViewing the differences between files
To display local modifications in a specified file in your working copy against the one in the repository, type:
svn diff (PATH of the file) (URL of the project's repository) --revision (-r) REV, --old OLD-TARGET, --new NEW-TARGET, --extensions (-x) "ARGS", --non-recursive (-N), --diff-cmd CMD, --notice-ancestry, --username USER, --password PASS, --no-auth-cache, --non-interactive, --no-diff-deleted, --config-dir DIRExporting a clean directory tree on your local machine
You can extract an unversioned copy, that is, a clean directory of a tree, on your local machine from the project repository or from within your local working copy. To get a clean directory of an older revision from the repository, type:
svn export [-r REV] [PATH] --revision (-r) REV, --quiet (-q), --force, --username USER, --password PASS, --no-auth-cache, --non-interactive, --config-dir DIRThis will export a clean directory tree from the repository specified by URL, at a revision REV (if specified), otherwise at HEAD, into PATH. If PATH is omitted, the last component of the URL is used for the local directory name. Alternatively, you can also export a clean directory tree from the working copy specified by PATH1 into PATH2 within your local machine. This will preserve all local changes, but will not copy files under version control. To achieve this, type:
svn export PATH1 PATH2Contributing your changes to the SVN repository
After making changes to files and/or directories locally, you must commit those changes to the SVN repository.
Committing your changes
To commit your changes into the shared repository, type:
svn commit -m "Type your comment here" --message (-m) TEXT, --file (-F) FILE, --quiet (-q), --non-recursive (-N), --targets FILENAME, --force-log, --username USER, --password PASS, --no-auth-cache, --non-interactive, --encoding ENC, --config-dir DIRIf you do not include a description of your change to the file, you will be prompted to add it by invoking your file editor before svn can complete the commit action or you will get a «Commit failed» error. All commits are logged automatically and posted to the project’s commits discussion.
Importing an unversioned file or tree in the project repository
You can recursively commit an unversioned file or tree into the project repository using svn import. Parent directories are created in the repository as required. The following command will recursively commit a copy from the PATH to the URL. If PATH is omitted «.» is assumed.
svn import [PATH] URL --message (-m) TEXT, --file (-F) FILE, --quiet (-q), --non-recursive (-N), --username USER, --password PASS, --no-auth-cache, --non-interactive, --force-log, --editor-cmd EDITOR, --encoding ENC, --config-dir DIR, --auto-props, --no-auto-propsPrinting information about paths in your working copy
You will from time to time need specific information about files in your working copy to execute certain subcommands. It will print exhaustive but useful information about items in your working copy paths in your working copy, including Path, Name, URL, Revision, Node Kind, Last Changed, author, Last Changed Revision, Last Changed Date, Text Last Updated, Properties Last Updated, and Checksum.
svn info --targets FILENAME, --recursive (-R), --config-dir DIRViewing list of directory entries in the repository
Before starting work on a project or fetching a ‘working copy’, you may want to see the contents i.e. directories and files in your project’s repository or view directory entries in your local working copy.
svn list --revision (-r) REV, --verbose (-v), --recursive (-R), --username USER, --password PASS, --no-auth-cache, --non-interactive, --config-dir DIRViewing commit log messages
You can view the individual file/directory histories of the files/directories in your ‘working copy’ or the repository to track revision information by typing:
svn log [PATH] --revision (-r) REV, --quiet (-q), --verbose (-v), --targets FILENAME, --stop-on-copy, --incremental, --xml, --username USER, --password PASS, --no-auth-cache, --non-interactive, --config-dir DIRMerging changes
You can run this command to tell Subversion to merge the latest versions of files from the repository into your working copies.
svn merge --revision (-r) REV, --non-recursive (-N), --quiet (-q), --force, --dry-run, --diff3-cmd CMD, --ignore-ancestry, --username USER, --password PASS, --no-auth-cache, --non-interactive, --config-dir DIRWorking with the repository
Creating a new directory
To create a new directory in your working copy, type:
svn mkdir PATH --message (-m) TEXT, --file (-F) FILE, --quiet (-q), --username USER, --password PASS, --no-auth-cache, --non-interactive, --editor-cmd EDITOR, --encoding ENC, --force-log, --config-dir DIRTo create a new directory in your project repository, type:
svn mkdir URLThe final component of the PATH or URL determines the directory name. A directory in the repository is created with an immediate commit, so it requires a commit message.
Moving a file or a directory
You can move a file or a directory within your working copy or within your project’s repository using:
svn move SRC DST --message (-m) TEXT, --file (-F) FILE, --revision (-r) REV, --quiet (-q), --force, --username USER, --password PASS, --no-auth-cache, --non-interactive, --editor-cmd EDITOR, --encoding ENC, --force-log, --config-dir DIRThis command is equivalent to an svn copy followed by svn delete. Moving a file or a directory within your working copy moves and schedules it for addition for the next commit. Moving a file or a directory within your project repository is an atomic commit, so it requires a commit message.
Working with properties
Subversion has a number of specific properties that affect or determine it’s behavior. You can modify, commit, and revert property changes just like the contents of your files. You can delete, edit, print, list, set a property from files, directories or revisions from your local working copy or your project’s repository.
svn propdel, svn propedit, svn propget, svn proplist, svn propsetResolving conflicts
You may get a conflict while updating your local working copy. You will need to resolve the conflict. After resolving, type:
svn resolved PATH --targets FILENAME, --recursive (-R), --quiet (-q), --config-dir DIRReverting your changes
As you work with Subversion, you will realize that svn revert PATH… is equivalent to a Ctrl Z on Windows. You can:
- Revert any local changes on your local working copy and thus, resolve any conflicted states.
- Revert the contents of an item and the property changes in your working copy.
- Cancel out any scheduling operations like file addition, file deletion etc.
svn revert --targets FILENAME, --recursive (-R), --quiet (-q), --config-dir DIRGetting status of files/directories
It is a good practice in version control to review your changes before committing them to the project’s repository. You can run svn status to print the status of the files and directories in your working copy. This will result in a coded eight-column output. It is humanly impossible to draw an ‘error-free’ conclusion from the output as each column has an exhaustive legend. To make this task simpler and simultaneously see an example, type svn help status in your command prompt.
svn status --show-updates (-u), --verbose (-v), --non-recursive (-N), --quiet (-q), --no-ignore, --username USER, --password PASS, --no-auth-cache, --non-interactive, --config-dirSwitching your working copy
You can update your working copy to mirror a new URL using:
svn switch URL [PATH] --revision (-r) REV, --non-recursive (-N), --quiet (-q), --diff3-cmd CMD, --relocate, --username USER, --password PASS, --no-auth-cache, --non-interactive, --config-dir DIRUpdating your working copy
As a good version control practice, it is recommended that you update your local working copy with the project repository everyday using:
svn update [PATH...] --revision (-r) REV, --non-recursive (-N), --quiet (-q), --diff3-cmd CMD, --username USER, --password PASS, --no-auth-cache, --non-interactive, --config-dir DIRThe updated items listed with their current status indicated as follows:
- A = A file was added to your working copy.
- U = A file was updated to your working copy.
- D = A file was deleted from your working copy.
- R = A file was replaced in your working copy.
- G = A file was successfully merged.
- C = A file has merge conflicts that must be resolved by hand
Branching and tagging
A project’s trunk is usually used for the mainline of development whereas branches are usually used for variations on that line. A branch is an ongoing line of development. In a Software Development Life Cycle, branches are often used when a public release of a software product is due, to allow testers to work on the release candidate so that new development can go on independently of the testing. Branches are also used for experimental work and a complete code rewrite. Tagging is a way of marking a group of file revisions as belonging together. Though branches and tags are created using the svn copy subcommand, branches and tags are different things. A branch represents multiple revisions while a tag represents a single revision.
The Subversion repository for your project hosted on this site supports branching and tagging your source files. Tagging and branching are easy and practical ‘copy’ operations for Subversion.
To create a branch or tag project files, type:
svn copy SRC DST -m "Type your message here"