Search/Navigation:
Related:
SLAC/EPP
/HPS Public
Jefferson Lab/Hall B
/HPS Run Wiki
S30XL-LESA/LDMX
Table of Contents | ||||
---|---|---|---|---|
|
...
It includes definitions of basic terminology plus explanations and examples of basic commands.
The version of Subversion (no pun intended) is important because older versions are not compatible with newer ones, meaning you cannot checkout a project with say 1.8 and then use a 1.6 client on it. This is because the metadata formats used to track local files changes with minor release numbers in incompatible ways.
You can use this command to upgrade your local copy from an older client to the newer one.
No Format |
---|
cd sandbox; svn upgrade . |
You should also make sure that your IDE's Subversion library is compatible with the command line client (covered in Project Development in Eclipse).
Here are some basic terms with which you should be familiar in order to understand the rest of this guide.
...
The Subversion command line client is executed from a shell with the "svn" (note lower-case) command. (This is not to be confused with SVN in all upper case!)
...
A working copy is your local version of any SVN module or file from the remote repository. Executing an svn checkout will create a local copy of a file or directory.
The master copy refers to the current version of a file on the SVN server, as opposed to a local copy on your computer.
Executing a commit will push your changes on to one or more files or directories to the remote repository, making the master copy match your current local copy of those files.
A revision in SVN is a globally unique number identifying identifier, starting with 'r', that tags the state of the repository at some particular time. Every commit will create a new revision. The revision numbers are numbered sequentially from 1 to however many revisions have been created. (SVN actually tracks revisions globally rather than on a per file basis.)
URLs in SVN are used to identify paths on the remote server which has the master copy of the source code. In the case of Subversion, these These will have svn:// as the protocol. . (SVN supports other protocols as well such as https.)
For example, svn://svn.freehep.org/hps is the URL for the HPS Subversion repository.
...
In general, if you execute svn commands within a local directory that is tracked by Subversion, they will be interpreted correctly.
The base URL node of the remote repository such as svn://svn.freehep.org/hps/. This is similar to the root node in a file system.
The "^" character can be used to specify the repository root for any command that accepts a Subversion URL.
...
Any part of the repository under the root. Structure nodes can be conceptualized as a sub-directory on a file system, with the repository root as the root directory.
This is a copy of some directory the code at a certain point in time like , usually when a release is made. By convention, a tag should not be modified once created. They are usually kept in a node called 'tags'.
...
This is a fork of the trunk, or even of another branch, which is for development and can be modified after it is created. Branches are usually kept in a node called 'branches'.
To merge means combining together two nodes in order to merge their changes togetherMerging will combine together the contents of two nodes. This usually occurs when a branch should be reintegrated into the trunk or another branch.
To revert means clobbering your local changes in the working copy and replacing them with the current copy from the remote repository.
...
These are the settings I use for HPS projects.
No Format |
---|
global-ignores = target *.class *.jar *.diff x.x *.log .classpath .project .settings *.tar.gz .cproject gmon.out *.slcio .dependencies |
...
All commands below assume that you are in a command shell like bash on Linux and that the current working directory is a local working copy of a structure node that has been checkout checked out of the repository.
Text written like this indicates a Subversion command that can be executed from your terminal.
Note that some (most) arguments to these commands like path/to/file are completely bogus and should be replaced by valid files in your working copy or the remote repository (depending on the command).
svn co svn://repo/some/dir
This command will print out general repository information like your current revision # and the repository root.
svn info
Check the status of your local working copy
This command will list all your changes and additions in the local working copy:
The svn co or svn checkout command is used to make a local copy of a remote file.
For instance, you can checkout the entire HPS Java trunk.
No Format |
---|
svn co svn://svn.freehep.org/hps/java/trunk |
By default, all sub-nodes will be checked out recursively.
You cannot actually checkout a single file from SVN, only structure nodes.
The svn info command will print out useful information about your working copy.
For instance, this is the result of that command executed on my copy of the HPS Java trunk.
No Format |
---|
[$] svn info
Path: .
Working Copy Root Path: /u1/projects/eclipse/luna/java_workspace/hps-java_trunk
URL: svn://svn.freehep.org/hps/java/trunk
Relative URL: ^/java/trunk
Repository Root: svn://svn.freehep.org/hps
Repository UUID: 044bc1e2-196f-4772-ab28-abfd6a072e98
Revision: 1275
Node Kind: directory
Schedule: normal
Last Changed Author: lcdprod
Last Changed Rev: 1272
Last Changed Date: 2014-10-22 16:44:16 -0700 (Wed, 22 Oct 2014)
|
By default svn info will look at the current working directory but it can also take a directory or file as an argument.
No Format |
---|
svn info parent/pom.xml
svn info parent |
You can use the svn info command to show the status of local files compared to their remote versions on the server.
From the root directory of your working copy, this command will show all changes that have been made to the node.
No Format |
---|
svn status |
This command will return a list of files and directories that are different from their remote copies.svn status
Each file will have a letter next to it indicating its status, such as:
M = locally modified
? = not tracked by Subversion
A = added but not committed
D = deleted but not committed
etc.
Check the SVN docs for Here is a full list of all these abbreviationsstatus codes.
...
svn ls some/relative/path/
or
svn ls svn://repo/some/path/
svn up
This command can be used to add files:
svn add rel/path/to/file1 rel/path/to/file2
These will then be pushed to the remote repository when you execute a commit.
Delete files from the repository
This command can be used to delete files:
svn rm rel/path/to/file1 rel/path/to/file2
The deletion will occur when you commit.
To delete files use this command:
svn rm /path/to/file
You also need to perform a commit to delete the files in the repository and not just the local copy.
This command is used to commit your local changes to the repository:
svn commit -m "committing some stuff" [optional/path/to/file1] [optional/path/to/file2]
The list of files or directories to commit is optional, but it is usually a good idea to include it.
svn cp src/dir/or/file target/dir/or/file
svn mkdir path/to/dir
The ls command is similar to the equivalent Unix command. It can be used to list directory contents.
This is an example of listing contents of a relative path.
No Format |
---|
svn ls trunk/parent |
This command can also be used with absolute SVN URLs.
No Format |
---|
svn ls svn://svn.freehep.org/hps/java/trunk |
The up command is used to synchronize your local of files and directories with the remote repository.
Assuming you are in a local working directory, this command will pull all updates from the server.
No Format |
---|
svn up . |
The add command is used to add new files to the repository.
No Format |
---|
svn add sandbox/castle.txt |
This command does not actually push the files to the server but schedules this to occur. A commit must be executed in order actually perform the addition of the files.
The command can also be used on directories, in which case the default behavior is that all files under the directory will be added too. (Make sure this is actually what you want before committing!)
Files can be deleted from the repository using the rm command.
No Format |
---|
svn rm sandbox/castle.txt |
Similar to how adding files works, the deletion will not occur until you commit.
In order to update the master copy of any file or directory on the server, a commit must be performed first.
This is an example of committing a local file.
No Format |
---|
svn commit -m "Add castle to sandbox." sandbox/castle.txt |
Though this command can be executed without any arguments, it is a good idea to always list explicitly the files you want to include in your commit. Otherwise, every file which is modified locally will be part of the commit, which you may not want.
Files can be copied so that their revision history is kept.
No Format |
---|
svn cp sandbox/castle.txt sandbox/citadel.txt |
A commit is required to perform this action once it is scheduled.
Moving files or directories is very similar to copying or deleting.
No Format |
---|
svn mv sandbox/castle.txt sandbox/citadel.txt |
This command will schedule a deletion of the first file and an addition of the second, copying the revision history from the first to the second. A commit must be executed to perform this command once it is scheduled.
Warning | ||
---|---|---|
| ||
Making branches is an advanced operation. Ask a knowledgeable individual for advice before doing this for the first time. After branching to make major changes in the code, you should make sure to change your IDE or editor to use the branched node instead of the trunk. |
Branching is actually a special case of copying where a structure node is copied to a new location and then development is performed on this new copy. This is a basic way for developers to "fork" the code in an organized fashion so that any potentially disruption changes are kept isolated from the trunk until the code is made stable and working again.
This is an example of making a branch.
No Format |
---|
svn cp -m "Making a new HPS Java branch for some reason." ^/projects/hps/java/trunk ^/projects/hps/java/branches/HPSJAVA-123 |
The name of the branch is 'HPSJAVA-123' to reference a JIRA item. This is just a dummy name. In actuality, it should be a real JIRA item. This allows someone to understand the purpose of that branch from its name.
...
Warning | ||
---|---|---|
| ||
Merging is an advanced operation, and should not be done without some forethought. Always use '--dry-run' to check the results of the command before actually executing it. And always merge equivalent structure nodes when merging a branch back into the trunk, or you will screw up the trunk. |
Merge a branch into the trunk:
svn merge ^/projects/foo/branches/v01-02-03/ ^/projects/foo/trunk
This is an advanced command so don't use it unless you know what you're doing.
Same command which just prints what would happen:
svn merge ^/projects/foo/branches/v01-02-03/ ^/projects/foo/trunk
Merging is the process of including changes from one node in the repository into another. After working on a branch, for instance, you will usually at some point want to integrate the changes make on the branch back into the trunk.
Using the above example branch, the following is the equivalent merge operation.
No Format |
---|
svn merge ^/projects/hps/java/branches/hps-java_HPSJAVA-123/ ^/projects/hps/java/trunk |
In general, unless very minor changes were made to the code on the branch, you should always communicate with the other developers about plans for merging and what the state of the trunk will be after the merge is performed.
After a merge, the changes (additions, deletions, etc.) are only After a merge, the changes are made to the local copy and must still be committed, using the usual commit command.
...
...
...
svn cp m "making a branch" ^/projects/foo/trunk ^/projects/foo/branches/foo-dev
...
...
Warning | ||
---|---|---|
| ||
Making tags is an advanced operation. Most general users do not need to make tags, and for Maven projects this is done automatically during the release procedures. Never change a tag once it is made. Should changes be required, the preferred method is making them in the trunk and then making a new tag. |
Creating tags in SVN is actually just another case of copying nodes. In fact, there is no good way to actually make a read-only, fixed copy of the files at any given time in SVN, so tags are essentially a convention and not something that is actually supported! Once a tag is made of the code, it should generally not be modified. (That's what the trunk and branches are for.)
This is a (dummy) example of making a tag of the whole trunk.
No Format |
---|
svn cp -m " |
...
Making a bogus tag of the trunk." ^/projects/ |
...
hps/java/trunk ^/projects/hps/ |
...
java/tags/ |
...
hps-java-1.2.3 |
The versions in actual tags within the HPS repository will correspond to releases made using Maven and Jenkins.
svn revert path/to/broken/local/file
Warning | ||
---|---|---|
| ||
This command should usually be done by the repository administrator. To have Subversion ignore files in your local copy, see the section above entitle "Global config for ignoring files". |
Files can have properties on them. This can be used to alter the behavior of Subversion.
For instance, this command will cause all files with the .log extension to be ignored in the current directory.
svn propset svn:ignore "*.log" .
Sometimes you may want to revert a local file which will replace it with the equivalent file from the server.
For instance, this command will revert a single local file to its master copy, removing any changes you have made on it locally.
No Format |
---|
svn revert sandbox/castles.txt |
The command will execute immediately unlike an addition or deletion.
You can also revert entire nodes recursively, which will replace all changes in and under that node with the master copy.
No Format |
---|
svn revert sandbox --recursive |
You should be careful when reverting entire nodes, as this will completely clobber any changes you have made.
Using revert results in changes to your local copy that are not recoverable e.g. all your local edits will be removed. So be careful when using this command.
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...