Applying Unix Filesystem Attributes to Files under Version Control

If you work with Eclipse on a computer that is running Unix, you might want to store Unix file system attributes with files that you check in to version control. For example, you might want to specify that a file in version control be made executable when it is retrieved from version control. Visual Studio Team Foundation Server does not provide a means to store this information with the file that is added to version control. However, you can specify a file that is named .tpattributes in any working folder. If that file exists when you retrieve files from version control, the contents of that file specify which attributes should be set on files in that folder.

You can add the .tpattributes file to version control. When any team member retrieves that file to their working folder, Team Explorer Everywhere will set attributes based the contents of the file. If the .tpattributes file is deleted from disk, subsequent get operations on files in that directory will cause their attributes to revert to their default states. Attributes also revert to their default states for files whose .tpattributes lines are removed or are made into comments.

Format of the .tpattributes File

The .tpattributes file is a text file with a simple format. You must create this file manually.

Backus-Naur Form (BNF)

The syntax of the .tpattributes file, as represented in BNF, is as follows:

    <.tpattributes>         ::= { <line> }
    <line>                  ::= <comment-line> | <directive-line> <EOL>
    <comment-line>          ::= "#" <ignored-text>
    <directive-line>        ::= <file-expression> ":" <attribute> { "|" <attribute> }
    <attribute>             ::= <boolean-attribute> | <string-pair-attribute>
    <string-pair-attribute> ::= <key> "=" <value>

Most whitespace is ignored when Team Explorer Everywhere parses this file. Leading and trailing whitespace is ignored when parsing <line>, <file-expression>, <boolean-attribute>, <key>, and <value>. Malformed lines are ignored. Unknown attributes are also ignored and other recognized attributes are still applied.

Example .tpattributes file

    # Lines that begin with #, like this one, are ignored.
    build.sh:x
    README.txt:y|z=m
    include:link=$/Project/include
    docs:link=../extras/docs
    # The following line makes all Perl files executable.
    .*\.pl:x
    # The following line matches both \"cleanzpl\" as well as \"clean.pl\" and sets both the x and u attributes.
    clean.pl:x|u

The first field of a non-comment line is a file name or regular expression, without any leading path information. This file name or expression refers to a file or directory in the same directory where the .tpattributes file exists. The file name is ended by a colon (which Team Foundation Server does not allow in its file paths and is not a special regular expression character). The part after the colon is a list of attributes, all of which apply to the named item, delimited by a pipe character (|). An attribute is either a string pair attribute (for example, "link=$/Project/include") or a boolean attribute (for example, "x").

Supported Attributes

Team Explorer Everywhere supports the following attributes in the .tpattributes file. The descriptions for each attribute specify which attributes can be combined.

x

This attribute represents a boolean value that specifies that the named file will be made executable after it is written to disk. This attribute is supported by Team Explorer Everywhere only on computers that are running Unix (this includes Mac OS X) and cannot be applied to directories. Team Explorer Everywhere will turn on the execute bits according to the umask for that user. The x attribute may generally be combined with other attributes (some exceptions apply).

When multiple files are matched by a regular expression, the executable attribute is applied to all files.

link=<path>

This attribute consists of a string pair and specifies that a symbolic link should be created in place of the file name that was specified on this directive line. This file must exist in version control for a link to be created. The contents of the file are ignored if a link is to be created in its place.

The value of the link attribute is the relative or absolute path of a server that is running Team Foundation Server, and this path specifies where the symbolic link should point. Before Team Explorer Everywhere will create a symbolic link, it verifies whether the link destination is mapped to a working folder in the current Team Foundation Server workspace. If so, the link is created to point to the item on disk. If the destination is not mapped, the symbolic link is not created because Team Explorer Everywhere cannot determine the target of the link. When this occurs, the file contents from Team Foundation Server are put on disk instead.

When multiple files are matched by a regular expression, each file is created as a link to the link value.

local-link=<path>

This attribute consists of a string pair that specifies that a symbolic link should be created in place of the file name specified on this directive line. This file must exist in version control for a link to be created. The contents of the file are ignored if a link is to be created in its place.

The value of the local-link attribute is a literal local path that specifies the target of the symbolic link. The local path is not interpreted by either client for Team Explorer Everywhere. The local path is given to the operating system and can be any path style (relative or absolute) that is accepted by the symlink function of the operating system.

When multiple files are matched by a regular expression, each file is created as a link to the link value.

The local-link attribute overrides the link attribute if both are specified for a file. For example, if link is applied to a regular expression matching all .txt files (".*\.txt"), but local-link is applied for file.txt, a local link is created for file.txt.

client-eol=<eol-style>

This attribute consists of a string pair that enables automatic conversion of line endings to the named style when a file is written to a working folder during a get operation. A file can have one or both of the client-eol and server-eol attributes set for it. When this attribute is set for a file, all line styles of line endings are converted to the named style.

The value of the client-eol attribute is one of the following end-of-line styles:

Examples

Makefile: client-eol=native
build.sh: x | client-eol=lf

server-eol=<eol-style>

This attribute consists of a string pair that enables automatic conversion of line endings to the named style when a file is sent to the server for a check-in or shelve operation. A file can have one or both of the client-eol and server-eol attributes set for it. When this attribute is set for a file, all line styles of line endings are converted to the named style.

The value of the server-eol attribute is one of the end-of-line styles as described in the previous table for the client-eol attribute.:

Examples

win32-module.c: client-eol=native | server-eol=crlf
Makefile.MacOS9: server-eol=cr

transform=<format>

This attribute consists of a string pair that enables automatic conversion from a native file format on the client into a different format on the instance of Team Foundation Server. The file is transformed when it is sent to the server for a check-in or shelve operation, and is transformed into its native format when it is retrieved from the server by a get operation.

The value of the transform attribute is one of the following encoding techniques:

Transform

Encoding used

apple

This causes Mac OS-specific metadata to be preserved in a file on the local filesystem, including the resource fork, Finder info, and Finder comments. Without this attribute, resource forks will not be checked in to Team Foundation Server. Note This attribute value is supported for Team Explorer Everywhere clients only on computers that are running the Mac OS X operating system. On other operating systems, this value is ignored.

Examples

MacOS9Application: x | transform=apple

See Also

Other Resources

Placing Files under Version Control (Team Explorer Everywhere)

Excluding Eclipse Project Resources from Version Control