svnant

http://subclipse.tigris.org/svnant/svntask.html

Description

This task provides an interface to Subversion     revision control system that is a compelling replacement for CVS in the open source community.

The setup of these external tasks can be studied here.

Parameters

The following parameters are supported by the svn task:

Attribute	Description	Required
username	username that will be used for all nested svn commands. Deprecated. This attribute won't work with SVNANT 1.3.2+ . Use refid for svnSetting instead.	No
password	password that will be used for all nested svn commands. Deprecated. This attribute won't work with SVNANT 1.3.2+ . Use refid for svnSetting instead.	No
javahl	Set to "false" to use command line client interface instead of JNI JavaHL binding. Deprecated. This attribute won't work with SVNANT 1.3.2+ . Use refid for svnSetting instead.         Default: true	No
svnkit	Set to "false" to use command line client interface instead of SVNKit binding. Deprecated. This attribute won't work with SVNANT 1.3.2+ . Use refid for svnSetting instead.         Default: false	No
dateFormatter	formatter definition used to format/parse dates (e.g. when revision is specified as date). Deprecated. This attribute won't work with SVNANT 1.3.2+ . Use refid for svnSetting instead.         Default: MM/DD/YYYY HH:MM AM_PM	No
dateTimeZone	time zone used to format/parse dates (e.g. when revision is specified as date). Deprecated. This attribute won't work with SVNANT 1.3.2+ . Use refid for svnSetting instead.         Default: local	No
failonerror	Controls whether an error stops the build or is merely reported to the screen. Deprecated. This attribute won't work with SVNANT 1.3.2+ . Use refid for svnSetting instead.         Default: true	No
logFile	Write the output of the commands into the log file instead of the console.	No
refid	If set the configuration for this task is taken from a svnSetting object. Such a settings instance simply provides default values, so they will be overridden in case the corresponding attribute on this task has been set.	No

Svn commands specified as nested elements

add	cat	checkout	cleanup	commit
copy	createRepository	delete	diff	diffSummarize
export	ignore	import	info	keywordsadd
keywordsremove	keywordsset	list	log	mkdir
move	propdel	propget	propset	revert
singleinfo	status	switch	update	wcversion

add

You can add files and directories to svn repository with nested <add> elements.

Attribute	Description	Required
file	file to add to the repository	No
dir	directory to add to the repository	No
recurse	Set to "false" to operate on a single directory only (applies only when dir attribute is set).         Default: true	No
force	Set to "true" to check the contents of a directory that is already under source       control for new directories/files (applies only when dir attribute is set).         Default: false	No

Parameters specified as nested elements :

• fileset
  

  Filesets are used to select sets of files to add to the repository.

  Note that directories needed to add selected files will be added to the repository     even if they are not selected by the fileset.

• dirset
      Dirsets are used to select sets of directories to add.

cat

Get the content of a file on repository.

Attribute	Description	Required
destFile	Name of the destination file         Default: The name of the file on the url placed in the ant project's basedir	No
url	Url of the file in repository	Yes
revision	revision to get.Possible values are:        a date with the format as specified in dateFormatter attribute a revision number HEAD, BASE, COMMITED or PREV         Default: HEAD	No

checkout

Check out a working copy from a repository.

Attribute	Description	Required
recurse	Set to "false" to operate on single directory only. Don't use this in combination with 'depth' !           Default: true	One of these
depth	Specifies which resources have to be checked out. Following values are legal:        empty : Just checkout the top level (empty directory). files : Just checkout toplevel files. immediates : Checkout toplevel files and directories (unpopulated). infinity : Checkout everything. Don't use this in combination with 'recurse' !
ignoreexternals	If set to true svn externals will be skipped. Only in combination with 'depth' !         Default: false	No
force	Enforces the execution of the checkout commands. Only in combination with 'depth' !         Default: false	No
url	url to checkout from	Yes
destPath	destination directory	Yes
revision	revision to checkout.Possible values are:        a date with the format as specified in dateFormatter attribute a revision number HEAD, BASE, COMMITED or PREV         Default: HEAD	No

cleanup

cleanup your working copy

Attribute	Description	Required
dir	directory to cleanup	Yes

commit

Send changes from your working copy to the repository.

Attribute	Description	Required
file	file to commit	No
recurse	Set to "false" to operate on single directory only. Apply only when dir attribute is set.         Default: true	No
dir	directory to commit	No
message	commit message	Yes

Parameters specified as nested elements :

• fileset
      Filesets are used to select sets of files to commit.
• dirset
      Dirsets are used to select sets of directories to commit.

copy

Duplicate something in working copy or repository, remembering history.

source and destination can each be either a working copy (WC) path or URL:

• WC->WC: copy and schedule for addition (with history)
• WC->URL: immediately commit a copy of WC to URL
• URL->WC: check out URL into WC, schedule for addition
• URL->URL: complete server-side copy;  used to branch & tag

Attribute	Description	Required
srcPath	source path	One of these
srcUrl	source url
destPath	destination path	One of these
destUrl	destination url
message	commit message	when destUrl is set
revision	revision to copy from (when srcUrl is set).Possible values are:        a date with the format as specified in dateFormatter attribute a revision number HEAD, BASE, COMMITED or PREV         Default: HEAD	No
makeParents	Create parents first (only useful for copies from srcUrl to destUrl).         Default: false	No

createRepository

Create a new, empty repository at path.

Attribute	Description	Required
path	Path where to create the new repository	yes

Example:

    <createRepository path="repository"/>
  

delete

If run on a working copy target, the item is scheduled for deletion upon the next commit.   Files, and directories that have not been committed, are immediately removed from the working   copy.

The command will not remove targets that are, or contain, unversioned or modified items;   use the force attribute to override this behaviour.

If run on an url, the item is deleted from the repository via an immediate commit.

Attribute	Description	Required
file	file to delete	No
url	url to delete	No
dir	directory to delete	No
message	commit message	when url attribute is set
force	forces the deletion         Default: false	No

Parameters specified as nested elements :

• fileset
      Filesets are used to select sets of files to delete.
• dirset
      Dirsets are used to select sets of directories to delete.

diff

Display the differences between two paths (oldPath and newPath) or two urls (oldUrl and newUrl).

Attribute	Description	Required
oldPath	the old path           Default: .	One of these
oldUrl	the old url           Default: .
oldTargetRevision	the revision used for the comparison of the old repository         Default: BASE or, if oldUrl is set, to HEAD	No
newPath	the new path           Default: .	One of these
newUrl	the new url           Default: .
newTargetRevision	the revision used for the comparison of the new repository         Default: The current working version or, if newUrl is set, to HEAD	No
outFile	the destination file for the diff result         Default: patch	No
recurse	Set to "false" to operate on single directory only         Default: true	No

Example:

diff between BASE and current working version

    <diff 
        oldPath="workingcopy/diffTest/file.txt" 
        outFile="workingcopy/diffTest/patch.txt"
    /> 
  

diffSummarize

TO BE DONE

export

1. Exports a clean directory tree from the repository specified by srcurl,     at revision revision if it is given, otherwise at HEAD, into destPath.
2. Exports a clean directory tree from the working copy specified by srcPath into     destPath. all local changes will be preserved, but files not under revision control     will not be copied.   

Attribute	Description	Required
srcUrl	source url to export from	One of these
srcPath	source path to export from
destPath	destination path	Yes
force	Allows to overwrite an already existing destination.         Default: false	No
revision	revision of the source url to export from.Possible values are:        a date with the format as specified in dateFormatter attribute a revision number HEAD, BASE, COMMITED or PREV         Default: HEAD	No

ignore

Add a given file or a pattern to the ignored files list (modifies svn:ignore property)

Attribute	Description	Required
file	file to ignore	One of these
dir	directory to ignore
pattern	pattern to add to svn:ignore on the directory. Only when dir is set.	Yes
recurse	Set to "true" to add the pattern recursively to directories (only when dir is set).         Default: false	No

Examples:

    <ignore 
        dir="workingcopy/ignoreTest/dir1" 
        pattern="*.ignore" 
        recurse="true"
    />
  

import

Commit an unversioned file or tree into the repository.

Recursively commit a copy of path to url.

Attribute	Description	Required
path	source path to export from	Yes
url	source url to import to	Yes
newEntry	If set, copy top-level contents of path into url directly.        Otherwise, create newEntry underneath url and begin copy there.	No
message	commit message	Yes
recurse	Set to "false" to operate on single directory only.         Default: true	No

info

Gets the information from the repository for a file, directory or url and sets the values to ant properties.

Attribute	Description	Required
target	Directory or file to gather the information about.	Yes
propPrefix	Prefix to use for the properties.         Default: svn.info.	No
verbose	Default: false	No

The task sets the following properties (prefix applied accordingly):

Property	Description
path	Always
name	For files only
url	Always
repourl	Always
repouuid	Always
rev	Always
nodekind	Always
schedule	Always
author	Always
lastRev	Always
lastDate	Always
lastTextUpdate	For files only
lastPropUpdate	For files only
checksum	For files only

keywordsadd

Keywordsadd add some keywords to be substituted on the given files. Present keywords are not modified.

The attributes are the same than for keywordsset command.

keywordsremove

Keywordsadd remove some keywords to be substituted on the given files. Other present keywords are not modified.

The attributes are the same than for keywordsset command.

keywordsset

Keywordsset controls which keywords will be substituted on the given files. Valid keywords are:

• URL, HeadURL : The URL for the head version of the object.
• Author, LastChangedBy : The last person to modify the file.
• Date, LastChangedDate : The date/time the object was last modified.
• Rev, LastChangedRevision : The last revision the object changed.
• Id : A compressed summary of the previous.

Attribute	Description	Required
file	File for which keywords will be substituted (specify nested filesets alternatively).	One of these
dir	All files in this directory will have their keywords substituted (recursively).         Specify nested filesets alternatively.
keywords	The keywords to substitute on the given files.	No
HeadURL	Set to "true" the keyword to substitute it on the given file.	One of these
URL	Set to "true" the keyword to substitute it on the given file.
Author	Set to "true" the keyword to substitute it on the given file.
LastChangedBy	Set to "true" the keyword to substitute it on the given file.
Date	Set to "true" the keyword to substitute it on the given file.
LastChangedDate	Set to "true" the keyword to substitute it on the given file.
Rev	Set to "true" the keyword to substitute it on the given file.
LastChangedRevision	Set to "true" the keyword to substitute it on the given file.
Id	Set to "true" the keyword to substitute it on the given file.

Parameters specified as nested elements:

• fileset
      Filesets are used to select the files where the keywords will be set.
• dirset
      Dirsets are used to select the directories where the keywords will be set.

list

lists the content of a repository

Attribute	Description	Required
delimiter	The delimiter to be used for separation of the list.         Default: ,	No
listDirs	If enabled directory entries will be listed.         Default: true	No
listFiles	If enabled file entries will be listed.         Default: true	No
onlyNames	If enabled only the names will be listed otherwise the complete urls.         Default: false	No
property	Property which will receive the resulting value.	Yes
recurse	Allows to list the complete subtree if true. Use it carefully.         Default: false	No
revision	The revision used to get the listing from.         Default: HEAD	No
url	The URL which content shall be listed.	Yes

log

Display commit log messages.

Attribute	Description	Required
path	path to create	One of these
url	url to create
startRevision	start revision	Yes
stopRevision	stop revision	Yes
destFile	destination file         Default: The name of the file on the url placed in the ant project's basedir.	No
asXml	Output log as xml.         Default: true	No
changedpathes	Include changed paths in the log.         Default: false	No
stopOnCopy	Useful for determining branch points.         Default: true	No
limit	Restricts output to the first n log messages.         Default: All in the range	No

mkdir

Create a new directory under revision control.

If target is a working copy path the directory is scheduled for addition in the working   copy.  If target is an url the directory is created in the repository via an immediate commit.

In both cases all the intermediate directories must already exist.

Attribute	Description	Required
path	path to create	One of these
url	url to create
message	commit message	Yes
makeParents	Create parents first.         Default: false	No

move

Move/rename something in working copy or repository.

Source and destination can both be working copy (WC) paths or URLs:

• WC  -> WC:   move and schedule for addition (with history).
• URL -> URL:  complete server-side rename.

Attribute	Description	Required
srcPath	source path	One of these
srcUrl	source url
destPath	destination path	One of these
destUrl	destination url
message	commit message	Yes

propdel

Remove a property from files or dirs.

Attribute	Description	Required
path	path of the file or directory on which to delete the property	Yes
name	name of the property to delete	Yes
recurse	if set, property will be removed recursively         Default: false	No

propget

Get a property from a file or a directory.

Attribute	Description	Required
path	path of the file or directory on which to get the property.	One of these
url	url of the file or directory in repository on which to get the property
name	name of the property to get	Yes
property	the name of the property to set with the value of the svn property	One of these
file	file that will contain the value of the property

Example:

    <propget 
        path="workingcopy/propTest/file.png" 
        name="svn:mime-type" 
        property="propTest.mimeType"
    />
  

propset

Set a property on files or dirs.

Attribute	Description	Required
path	path of the file or directory on which to set the property.	Yes
name	name of the property to set.	Yes
value	the value of the property	One of these
file	the file that will be used as a value
recurse	if set, property will be set recursively	No

Note: svn recognizes the following special versioned properties but will store any   arbitrary properties set:

• svn:ignore : A newline separated list of file patterns to ignore.
• svn:keywords : Keywords to be expanded.  Valid keywords are:
  
  • URL, HeadURL : The URL for the head version of the object.
  • Author, LastChangedBy : The last person to modify the file.
  • Date, LastChangedDate : The date/time the object was last modified.
  • Rev, LastChangedRevision : The last revision the object changed.
  • Id : A compressed summary of the previous 4 keywords.
• svn:executable : If present, make the file executable. This property cannot be set on a     directory.  A non-recursive attempt will fail, and a recursive attempt will set the property     only on the file children of the directory.
• svn:eol-style : One of 'native', 'LF', 'CR', 'CRLF'.
• svn:mime-type : The mimetype of the file.  Used to determine whether to merge the file,     and how to serve it from Apache.
      A mimetype beginning with 'text/' (or an absent mimetype) is treated as text.     Anything else is treated as binary.
• svn:externals : A newline separated list of module specifiers, each of which consists     of a relative directory path, optional revision flags, and an URL.  For example:
      foo http://example.com/repos/zig
      foo/bar -r 1234 http://example.com/repos/zag

revert

Restore pristine working copy file (undo most local edits).

Attribute	Description	Required
file	file to revert	No
dir	directory to revert	No
recurse	Set to "false" to operate on a single directory only (applies only when dir attribute       is set or a dirset is provided).         Default: false	No
revision	revision.Possible values are:        a date with the format as specified in dateFormatter attribute a revision number HEAD, BASE, COMMITED or PREV         Default: HEAD	No

Parameters specified as nested elements:

• fileset
      Filesets are used to select sets of files to revert.
• dirset
      Dirsets are used to select sets of directories to revert.

singleinfo

Similar to the info command with the difference that this one   allows to request a specific information.

Attribute	Description	Required
target	Directory or file to gather the information about.	Yes
property	The property that will be set. It will be set to an empty string if the information       could not be gathered.	Yes
request	Specifies the information that has to be retrieved. Following values are supported:      path name url repourl repouuid revision nodekind schedule author lastRevision lastDate lastTextUpdate lastPropUpdate checksum	Yes

status

Get the status of working copy files and directories.

Attribute	Description	Required
path	path of the file or directory	Yes
textStatusProperty	Name of the property to set to the status of the item.Allowed values:      non-svn normal : no modifications added missing : item is missing (removed by non-svn command) incomplete deleted replaced modified merged conflicted obstructed ignored external unversioned	No
propStatusProperty	Name of the property to set to the status of the item propertiesAllowed values:        normal : no modifications conflicted modified	No
revisionProperty	Name of the property to set to the revision of the item (or "" if unversioned)	No
lastChangedRevisionProperty	Name of the property to set to the last changed revision of the item (or "" if unversioned)	No
lastChangedDateProperty	Name of the property to set to the last changed date of the item (or "" if unversioned).       The date is formatted according to task's "dateFormatter"	No
lastCommitAuthorProperty	Name of the property to set to the last commit author (or "" if unversioned).	No
urlProperty	Name of the property to set to the url of the item.	No

Example:

    <status 
        path="workingcopy/statusTest/added.txt" 
        textStatusProperty="testStatus.textStatus" 
        propStatusProperty="testStatus.propStatus" 
        lastChangedRevisionProperty="testStatus.lastCommitRevision" 
        revisionProperty="testStatus.revision" 
        lastCommitAuthorProperty="testStatus.lastCommitAuthor"
    />
  

switch

Update the working copy to mirror a new URL within the repository. This behaviour is   similar to 'svn update', and is the way to move a working copy to a branch or tag within the   same repository.

Attribute	Description	Required
path	The working copy to switch to the given url.	Yes
url	The url to switch to.	Yes
recurse	Set to "false" to operate on a single directory only.         Default: false	No
revision	revision.Possible values are:        a date with the format as specified in dateFormatter attribute a revision number HEAD, BASE, COMMITED or PREV         Default: HEAD	No

Example:

    <switch path="workingcopy/switchTest" url="${urlRepos}/switchTestBranch"/> 
  

update

Bring changes from the repository into the working copy. If no revision given, bring   working copy up-to-date with HEAD rev. Else synchronize working copy to revision.

Attribute	Description	Required
file	file to update	No
dir	directory to update	No
recurse	Set to "false" to operate on a single directory only (applies only if      dir has been set or a dirset has been given).         Default: false	No
revision	revision.Possible values are:        a date with the format as specified in dateFormatter attribute a revision number HEAD, BASE, COMMITED or PREV         Default: HEAD	No

Parameters specified as nested elements :

• fileset
      Filesets are used to select sets of files to update.
• dirset
      Dirsets are used to select sets of directories to update.

wcversion

Retrieves a state of the working copy. Similar to the svn's utility svnversion,   just providing more. Crawls the working copy and retrieves the maximum revision number,   revision range if workingCopy is mixed etc.

Attribute	Description	Required
path	a path to the working copy	Yes
prefix	a string which will be prefixed to output properties set/filled by this command	No
processUnversioned	flag whether presence of unversioned resoures should be treated as changes         Default: false	No

The command will set the following properties: (with optional prefix applied)

Property	Description
repository.url	URL of the repository of the working copy root
repository.path	path in the repository
revision.max	the highest revision number in the working copy
revision.max-with-flags	the highest revision number in the working copy plus flags (M - modified, X - mixed)
revision.range	the revision range (in mixed wc), similar to svnversion format. (e.g. 1000:1010MX)
committed.max	the highest 'last committed revision'
committed.max-with-flags	the highest 'last committed revision' plus flags (M, X)
modified	set to "true" if working copy is modified, property not set otherwise
mixed	set to "true" if working copy is mixed, property not set otherwise

An example of the properties that would be set in a sample working copy (with modifications,   with prefix="svn."):

svn.repository.url -> https://server/repos/branches/1.2.x
svn.repository.path -> /repos/branches/1.2.x
svn.revision.max -> 676
svn.revision.max-with-flags -> 676M
svn.revision.range -> 676M
svn.committed.max -> 651
svn.committed.max-with-flags -> 651M
svn.modified -> true

Examples

      <svn javahl="${javahl}">
          <checkout url="${urlRepos}" destPath="workingcopy" />
      </svn>
    

checkouts a working copy from repository

      <svn>
          <delete>
              <fileset dir="workingcopy/deleteTest">
                  <include name="**/*.del"/>
              </fileset>
          </delete>
          <commit message="commit deleted files" dir="workingcopy/deleteTest"/>
      </svn>    
    

deletes some files from repository (and commit changes)

      <svn>
          <add dir="workingcopy/propTest"/>
          <commit message="propTest added" dir="workingcopy/propTest"/>
          <propset 
              path="workingcopy/propTest/file.png" 
              name="svn:mime-type" 
              value="image/png"
          />
          <propset 
              path="workingcopy/propTest/file.png" 
              name="myPicture" 
              file="workingcopy/propTest/icon.gif"
          />
      </svn>
    

add my_repos/propTest to repository and set two properties on file.png

subversion command line interface is used (javahl="false").

      <svnSetting
          svnkit="true"
          username="bingo"
          password="bongo"
          id="svn.settings"
      />
      ...
      <svn refid="svn.settings" failοnerrοr="false">
        ...
      </svn>
    

Declaration of basic subversion settings and their reference. This little snippet     also shows that a setting can be overriden in the end (failonerror).