Edit online

Usually, you point to an item from a repository using a URL. However, sometimes this might not be enough because the URL alone might point to a different item than the one you want and a peg revision is needed.

A Subversion repository tracks any change made to its items by using revisions, which contain information such as the name of the author who made the changes, the date when they were made, and a number that uniquely identifies each of them. Over time, an item from a specific location in a repository evolves as a result of committing changes to it. When an item is deleted, its entire life cycle (all changes made to it from the moment it was created) remains recorded in the history of the repository. If a new item is created, with the same name and in the same location of the repository as a previously existing one, then both items are identified by the same URL even though they are located in different time frames. This is when a peg revision comes in handy. A peg revision is nothing more than a normal revision, but the difference between them is made by their usage. Many of the Subversion commands also accept a peg revision as a way to precisely identify an item in time, beside an operative revision (the revision regarding the used command).

Example:

To illustrate an example, consider the following:
  • A new repository file config was created, identified by the URL http://host.com/myRepository/dir/config.
  • The file has been created at revision 10.
  • Over time, the file was modified by committing revisions 12, 15, 17.
To access a specific version of the file identified by the http://host.com/myRepository/dir/config URL, you need to use a corresponding revision (the operative revision):
  • If a revision number is used that is lower than 10, an error is triggered, because the file has not been created yet.
  • If a revision number is used that is between 10 and 19, the specific version you are interested in would be obtained.
    Note: Although the file was modified in revisions 12, 15, 17, it existed in all revisions between 10 and 19. Starting with a revision where the file is modified, it has the same content across all revisions generated in the repository until another revision where it is modified again.

At this point, the file is deleted, creating revision 20. Now, no version of the file can be accessed because it no longer exists in the latest repository revision. This is due to the fact that Subversion automatically uses the HEAD revision as a peg revision (it assumes any item currently exists in the repository if not instructed otherwise). However, using any of the revision numbers from the 10-19 interval (when the file existed) as a peg revision (beside the operative revision), will help Subversion to properly identify the time frame when the file existed, and access the file version corresponding to the operative revision. If you use a revision number greater than 19, this will also trigger an error.

Continuing the example, suppose that at revision 30, a directory called config is created in the same repository location as the deleted file. This means that the new directory will be identified by the same repository address: http://host.com/myRepository/dir/config. If you only use this URL in any Subversion command, you will access the new directory. You will also access the same directory if you use any revision number equal to or greater than 30 as peg revision. However, if you are interested in accessing an old version of the previously existing file, then you must use one of the revisions that existed (10-19), as a peg revision, similar to the previous case.