SVN Plugin

Categories

The openBD SVN plugin lets you quickly and easily interact with a SVN repository. You can download or update files and directories in your repsitory as well as get some useful information. This plugin uses the SVNKit library to leverage functionality with the repository

Overview of functions

Function Name Description
SVNRegisterRepository Register a repository for use with SVN functions
SVNRemoveRepository Removes a previously registered datasource
SVNIsValid Test if a repository is valid
SVNUpdate Get files and directories from the given repository at a revision
SVNGetFile Returns the file at the given path and revision in the repository
SVNGetDir Fetches the files under given path and revision in the repository
SVNCommit Commits the specified actions
SVNLatestRevision Returns the latest revision number in the repository
SVNGetRevision Return revisions associated with a resource
SVNLogView Returns the latest revision number in the repository
SVNGetStatus Returns the file at the given path and revision in the repository
SVNDirectoryList For the given repository directory get the file contents
SVNDiff Get the diff of a file between revisions

To use any of the SVN plugin functions, you'll need the SVN server URL, and SVN credentials. A handy tip would be to store the credentials somewhere outside of a document repository for security purposes

Please note: all the following CFML snippets will assumed to be used inside CFSCRIPT unless otherwise stated.

Some useful SVN terminology

  • HEAD: The most recent revision, also referenced as -1
  • CREATE: The first revision, also references as 0
  • CheckSum: SVN calculated hash of the file
  • Diff the difference between to revisions of a file

SVNRegisterRepository

SVNRegisterRepository( name, url, user, pass, path, key );

Registering a SVN Repository is very similar to database datasource. Depending on the authentication model for you repository you may need to use different paramters. If registering the repository is successful, the name of the repository will be returned, otherwise it will return an empty string

If using a Key Authentication modal, SVNKit required a file to exist. To allow for different web application security models, there are different ways to handle this

  • Direct Key-File: If the file is stored somewhere in the filesystem that the application can reach, absolute path can be supplied.
  • Specific Temporary File: If a path, and a key are specified, the key will be written to the specified path.
  • Anonymous Temporary File: If is empty, and a key are specified, the key will be written to the system temp directory with a random file name.

If a Temporary Key File was used, the key file will be deleted when SVNRemoveRepository() is call for the given repository.

svnRepoName = "myRepository";
svnRepoURL = "svn+ssh://my.svnserver.com";
svnRepoUserName = "myUser";
svnRepoPassWord = "myPass";
svnKeyPath = "\svnKey.txt";
svnKey = fileRead(svnKeyPath);
svnKeyTempPath = "\tmp\svnKey.txt";

//Username, Password authentication
repoName = SVNRegisterRepository( svnRepoName, svnRepoURL, svnRepoUserName, svnRepoPassWord );

//Username, Password, Key-file authentication
repoName = SVNRegisterRepository( svnRepoName, svnRepoURL, svnRepoUserName, svnRepoPassWord, svnKeyPath );

//Username, Password, Key authentication, specify temp file
repoName = SVNRegisterRepository(svnRepoName, svnRepoURL, svnRepoUserName, svnRepoPassWord, svnKeyTempPath, svnKey);

//Username, Password, Key authentication, anonymous temp file
repoName = SVNRegisterRepository(svnRepoName, svnRepoURL, svnRepoUserName, svnRepoPassWord, "", svnKey);

SVNRemoveRepository

SVNRemoveRepository( name );

This is used to deregister a SVN repository. If a Temporary Key File was created, when the repository was registered, it will be deleted.

svnRepoName = "myRepository";

repoName = SVNRemoveRepository( svnRepoName );

SVNIsValid

SVNIsValid( name );

Checks to see if a given Repository has been previously registered using SVNRegisterRepository(), returning a boolean indicator 

svnRepoName = "myRepository";

repoStatus = SVNIsValid( svnRepoName );

SVNUpdate

SVNUpdate( name, svnPath, localPath, revision, recursive, properties );

Download content from the SVN repository. SVNUpdate can work with files, and directories. If properties are not requested back, SVNUpdate will return a boolean to indicate if the target was successfully download. If properties are requested back, a struct will be returned with a key for each target item downloaded, and each will have subkeys for their SVN properties.

Properties may include (name may be slightly different, and availability may differ based on SVN configuration)

  • revision
  • committed-date
  • eol-style
  • keywords
  • checksum (This is needed to commit updates)
  • last-author
svnRepoName = "myRepository";
svnPath = "...";
localPath = "...";

//download a single specific file from the repository, as it exists at HEAD
//this will also work for downloading a directory (non-recursive)
updateStatus = SVNUpdate( svnRepoName, svnPath, localPath);

//download a single file/directory from the repository, as it exists at a given revision
updateStatus = SVNUpdate( svnRepoName, svnPath, localPath, 100);

//download an entire directory (recursively) from the repository, as it exists at a given revision, this has no effect for a file
updateStatus = SVNUpdate( svnRepoName, svnPath, localPath, -1, true);

//download a file/directory from the repository , and get the properties
updateProperties = SVNUpdate(svnRepoName, svnPath, localPath, -1, false, true);

SVNGetFile

SVNGetFile( name, svnPath, localPath, revision, properties );

SVNGetFile() preforms the same functionality as SVNUpdate(), but only for files. It is recommended to use SVNUpdate, unless the specific control is needed. An error will be thrown if a directory is passed to it.

SVNGetDir

SVNGetDir( name, svnPath, localPath, revision, recursive, properties );

SVNGetDir() preforms the same functionality as SVNUpdate(), but only for directories. It is recommended to use SVNUpdate, unless the specific control is needed. An error will be thrown if a file is passed to it.

SVNCommit

SVNCommit( name, actionElems, message, revision );

This is the function to make any/all update to the SVN repository. A boolean will be returned to indicate success of the operation.

Actions may be fed through 1 at a time, or in batch. The keys contained in an action will controll the action

Actions Keys Action taken
svnPath,localPath New file/folder
svnPath,content,charset New file with content
svnPath,localPath,checksum Update file/folder
svnPath,content,checksum,charset Update file with content
svnPath Delete file
svnPath,property,value,checksum Update file/folder property 
svnRepoName = "myRepository";
myCommitMessage = "Adding, update, deleting setting properties";
actions = [
  //this will add the designated file to SVN at the designated path
  {svnPath:"...",localPath:"..."},

  //this will add a file with the supplied content to SVN at the designated path
  {svnPath:"...",content:"...",charset:"..."},

  //this will update the designated file to SVN at the designated path
  {svnPath:"...",localPath:"...",checksum:"..."},

  //this will update a file with the supplied content to SVN at the designated path
  {svnPath:"...",localPath:"...",checksum:"...",charset:"..."},

  //this will delete a file at the designated SVN path
  {svnPath:"..."},

  //this will set the properties at the designated SVN path
  {svnPath:"...",property:"...",value:"...",checksum:"..."}
}

//commit the specified actions to the repository at HEAD
commitStatus = SVNCommit(svnRepoName, actions, myCommitMessage,-1);

SVNLatestRevision

SVNLatestRevision( name );

This will return the current HEAD revision of the repository

svnRepoName = "myRepository";
headRevision = SVNLatestRevision(svnRepoName);

SVNGetRevision

SVNGetRevision( name, svnPath, revision );

svnRepoName = "myRepository";
svnPath = "...";

//This is the most recent revision of the path
headRevisionOfPath = SVNGetRevision(svnRepoName,svnPath,"HEAD");

//This will be the revision before HEAD of the path
prevRevisionOfPath = SVNGetRevision(svnRepoName,svnPath,"PREVIOUS");

//This will be the revision the path was added to the repository
createRevisionOfPath = SVNGetRevision(svnRepoName,svnPath,"CREATE");

//This will get every revision the path was added/modified/deleted in
revisionHistoryOfPath = SVNGetRevision(svnRepoName,svnPath,"HISTORY");

//This will get the revision previous to the supplied revision
priorRevisionOfPath = SVNGetRevision(svnRepoName,svnPath,100);

SVNLogView

SVNLogView( name, startRevision, endRevision, filter, fileFilter, startDateFilter, endDateFilter);

This will retrieve the repository logs. Logs may include the following keys (depending on repository configuration

  • author
  • date
  • logMessage
  • revision
  • changed (this will contain an array of file/directories that were affected by the revision, and the type of action)
svnRepoName = "myRepository";

//Get all logs for a repository.  NOTE: This is not recommended
allLogs = SVNLogView( name );

//Get all logs starting at a given revision (inclusive)
logsSince = SVNLogView( name, 100 );

//Get all logs between (inclusive) the given revision
logsBetween = SVNLogView( name, 100, 200 );

//Get all logs looking for a pattern in the message, wildcards are implied before and after
logsWithMessage = SVNLogView( name, 0, -1, "..." );

//Get all logs for a given svn path
logsForPath = SVNLogView( name, 0, -1, "", "...");

//Get all logs from a given date
logsSinceDate = SVNLogView( name, 0, -1, "", "", "2000/12/30");

//get all logs between a given date range
logsBetweenDate = SVNLogView( name, 0, -1, "", "", "2000/1/1","2000/12/30");

SVNGetStatus

SVNGetStatus( name, svnPath, revision );

This will tell what time of item the path is. Possible values are

  • file
  • dir
  • none
svnRepoName = "myRepository";
svnPath = "...";

pathStatus = SVNGetStatus( svnRepoName, svnPath, -1 );

SVNDirectoryList

SVNDirectoryList( name, svnPath, recursive, listInfo, filter, sort, revision );

List the directory contents of a given path. This function take parameters similar to directoryList()

svnRepoName = "myRepository";
svnPath = "...";

//returns an array of paths (non-recursive) at the given directory
pathsArray = SVNDirectoryList( svnRepoName, svnPath );

//returns an array of paths (recursive) at the given directory
pathsRecursiveArray = SVNDirectoryList( svnRepoName, svnPath, false);

//returns an array of paths at the given directory
pathsArray = SVNDirectoryList( svnRepoName, svnPath, false, "path");

//returns an array of names at the given directory
namesArray = SVNDirectoryList( svnRepoName, svnPath, false, "name");

//returns a query of all the content at the given directory,
//will contain columns for name, datelastmodified, directory, size, type, revision ,author
directoryQuery = SVNDirectoryList( svnRepoName, svnPath, false, "query");

//returns an array of paths at the given directory, filtered accordingly
pathsTxtArray = SVNDirectoryList( svnRepoName, svnPath, false, "*.txt");

//return an array of paths at the given directory, ordered accordingly
pathsSortedArray = SVNDirectoryList( svnRepoName, svnPath, false, "","name asc");

//return an array of paths at the given directory, at the given revision
pathsSortedArray = SVNDirectoryList( svnRepoName, svnPath, false, "","",100);

SVNDiff

SVNDiff( name, svnPath, listInfo, revisionNewest, revisionOldest, splitRev, splitStartRevision, charset );

Returns the Diff information for a path between certain revisions.

svnRepoName = "myRepository";
svnPath = "...";
fileHead = SVNGetRevision( svnRepoName, svnPath, "HEAD" );
filePrev = SVNGetRevision( svnRepoName, svnPath, "PREVIOUS" );

//get the diff status struct
diffStuct = SVNDiff( svnRepoName, svnPath, "status", fileHead, filePrev );

//get the diff string for a file between 2 revisions
diffString = SVNDiff( svnRepoName, svnPath, "string", fileHead, filePrev );

//get the diff string formatted in HTML for a file between 2 revisions
diffHTML = SVNDiff( svnRepoName, svnPath, "html", fileHead, filePrev );

//get the diff struct for a file between 2 revisions
diffHTML = SVNDiff( svnRepoName, svnPath, "data", fileHead, filePrev );

The data structure when listInfo is data or overlay will have 2 keys; diff and revisions. Revisions is an array containing all the revisions covered in the diff. Diff is an array or all the lines covered in the diff

Code Status Line Keys Revision Keys Description
P Pristine status,source,revision line,status Each revision will have entry
A Add status,revision line,status,source Revisions prior to being added will not have an entry
D Removed status,revision line,status,source Revisions after being removed will not have an entry
U Updated status,revision line,status,source Revision that the change happened on will have status "U"

Example overlay

{ "diff": [
    { "status": "P",
      "source": "hello world!",
      "revision": {
        "1": {
          "line": 1,
          "status": "P"
        },
        "2": {
          "line": 1,
          "status": "P"
        }
      }
    },
    { "status": "U",
      "revision": {
        "1": {
          "line": 2,
          "status": "P",
          "source": "hola mundo."
        },
        "2": {
          "line": 2,
          "status": "U",
          "source": "hola mundo!"
        }
      }
    },
    { "status": "D",
      "revision": {
        "1": {
          "line": 3,
          "status": "P",
          "source": "hi world..."
        }
      }
    },
    { "status": "A",
      "revision": {
        "2": {
          "line": 3,
          "status": "A",
          "source": "Bonjour le monde!"
        }
      }
    }
  ],
  "revisions": [1,2]
}

© Copyright 2024 OpenBD Open Source Java CFML Runtime Engine . All Rights Reserved . Built & Powered By OpenBD