ln

create or change an element link or symbolic link

Usage

accurev ln [ -s ] [ -c <comment> ] [ -p ] <target> <link-name>
accurev ln -i <target>

Description

The ln command creates a new element link or symbolic link element, or changes the target of an existing link element. The link element’s status becomes (kept)(member). As with other kinds of element, you must promote a newly created or changed link in order to make it visible to other developers.

Although it can create a new element or change an existing one, the ln command does not cause a pre-create-trig or pre-keep-trig trigger to fire.

With the -i option, the ln command lists all the link elements in the workspace that point, directly or indirectly, to the specified target element.

The add command can also create element link and symbolic link elements, by converting existing link objects.

Element Links

An element link (or, more precisely, an “element-link element”) is an element whose content is a reference to another element. An element link is instantiated in a workspace tree or reference tree as a UNIX/Linux or Windows (on NTFS only) hard link.

Symbolic Links

A symbolic link (or, more precisely, a “symbolic-link element”) is an element whose content is a pathname. AccuRev does not check the validity of this pathname when the link is created or changed. Thus, any of the following might be true:

•	The target is an existing element (file, directory, or link) in the workspace.

•	The target is an (external) object in the workspace.

•	The target pathname is within the workspace, but no object currently exists at the pathname.

•	The target is not within the workspace at all (for example, c:\temp\junk or /tmp/foo). An object may or may not currently exist at the pathname.

On UNIX/Linux, a symbolic link element is instantiated in a workspace tree or reference tree as a UNIX/Linux symbolic link.

On Windows, a symbolic link element for directories only (and on NTFS file systems only) is instantiated as a Windows junction point.

Important! On Windows, an attempt to create a link to a non-directory element on NTFS, or to any any element on a non-NTFS (FAT, FAT32, NFS, etc.) file system will create the symbolic-link element but not the symbolic link itself, and display a warning similar to the one shown below.

Warning: The symbolic-link element was added/modified successfully, but the symbolic-link could not be instantiated on the local file-system: \.\mylink->\.\dir05\sub01

When updating a workspace located in a non-supported file system, an existing link to a directory generates an error (and update creates an empty, standard directory at the target location):

Re-linking "dir01sub03.mylink" - failed

Processing of Links by Commands

In general, an operating system command that processes a file’s contents (such as Windows type or copy, or UNIX/Linux cat or cp) will traverse an element link or symbolic link to a file. That is, if you specify the link object to the command, it will process the target of the link. Similarly, the Windows command dir and the UNIX/Linux command ls will traverse an element link or symbolic link to a directory.

In general, an AccuRev command, such as promote, processes a link object itself, not its target.

Options

–c <comment>

Specify a comment for the transaction. The next command-line argument should be a quoted string. Alternatively, the next argument can be in the form @<comment-file>, which uses the contents of text-file <comment-file> as the comment.

-i

List all element-link elements in the workspace that point to the specified target element, either directly or indirectly. Each such link element is reported on a separate line, in this format:

link-name -> direct-target-name

Both link-name and direct-target-name are reported as depot-relative pathnames. For a chain of links: L -> I1 -> I2 -> ... -> T, each intermediate link (I1, I2, etc.) will be the direct-target-name on one line and the link-name on another line.

-p

(for use with -s when the target is a depot-relative pathname) Converts the target pathname, which begins with /./ or \.\ , to a relative pathname.

UNIX/Linux: do not use -p if the target pathname begins with /./, but is actually an absolute pathname.

-s

Create a symbolic link. Default: attempt to create an element link. Returns an error if the target is not in the workspace.

<target>

When you’re creating an element link (no -s option), the target must be an element in the same workspace.

When you’re creating a symbolic link (-s option), you can use any kind of pathname to specify the target: simple filename, relative pathname, depot-relative pathname, or absolute. The contents of the symbolic link element is the pathname, exactly as you entered it (with one exception — see below).

More notes on specifying the target of a symbolic link:

•	You might need to enclose a relative pathname in quotes, to prevent the operating system from expanding the pathname to an absolute (full) pathname.

•	If the target does not currently exist, the newly created symbolic link element will have (missing-target) status.

•	Only an absolute pathname can indicate a location outside your workspace.

•	If you specify the target as a depot-relative pathname, you must also use the -p option; the target is automatically converted to a relative pathname, to enable operating-system commands to traverse the link:

$ pwd
/user/wks/john/dir02/sub03
$ accurev ln -p -s /./dir00/sub00/file00.txt myslink
Created symbolic-link /./dir02/sub03/myslink->../../dir00/sub00/file00.txt

<link-name>

The element link or symbolic link object to be created. If <link-name> already exists, its target is changed to <target>. You cannot create a circular chain of element links. You cannot overwrite an element link with a symbolic link, or vice-versa.

Note: Running "accurev ln directoryName linkName" will create a UNIX / Linux symbolic link, even though AccuRev creates an (elink).

Examples

Create an element link named relnotes, pointing to file release_notes.txt, which resides two directory levels up:

> accurev ln "../../release_notes.txt" relnotes

List all element links that point, directly or indirectly, to file release_notes.txt:

> accurev ln -i \.\doc\release_notes.txt
\.\install\README.txt->\.\doc\release_notes.txt
\.\README.txt->\.\install\README.txt

See Also

add, incl (to create cross-links between streams)

Techniques for Selecting Elements on page 10