Teamprise users on Unix platforms may wish to store some Unix filesystem attributes with the files they check in to Team Foundation Server source control. For instance, you may wish designate a file in source control be made executable when it is retrieved by a Teamprise client on a Unix platform. Unfortunately, TFS does not provide a means of storing this information at the time a file is uploaded to the source control server.
Starting with Teamprise 2.0, in order to support the specification of these file attributes Teamprise will look for a file named .tpattributes in any working folder where a file is retrieved. If this file exists, it is opened and read, and its contents specify which attributes should be set on files in that directory when they are put there by Teamprise. This .tpattributes file can be added to source control just like any other file, and as soon as other team members get it to their working folders, their Teamprise clients will also set attributes based on the file's contents.
Teamprise 3.0 and newer support Java regular expressions in the first field of .tpattributes files. Older versions only supported literal file names. If you use .tpattributes files with Teamprise 3.0 that you used with previous Teamprise versions, you may have to rewrite the files with precise regular expressions to prevent them from matching too many files. In practice this is not usually a problem because full file names do not include many special regular expression characters (the period character is the most common one).
See the Sun Java Tutorial Lesson: Regular Expressions for help.
The .tpattributes file is a text file with a simple format. Teamprise clients currently do not include functionality to create these files, so they must be created by developers or managers in a text editor.
The simple syntax of the .tpattributes file represented in Backus-Naur Form:
<.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>
Teamprise ignores most whitespace when parsing 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. These parse rules mean the following lines are all valid and will fully parse:
clean.pl:x|u
clean.pl: x|u
clean.pl :x | u
config.h:link=../include/config.h
config.h : link = ../include/config.h
My Objects : link = ../other/My Objects
clean.pl:x|u
.*\.sh:x
# Still valid since Teamprise 2.2, but matches "cleanzpl" as well as "clean.pl"
clean.pl:x|u
As the notation above declares, attributes may be combined with the pipe character. The following directive line sets both attributes x and y. See the Supported Attributes section for a list of supported attributes and details about which may be combined.
clean.pl:x|y
Here is an example .tpattributes file for Teamprise 2.2 and earlier:
# 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
And a similar file for Teamprise 3.0 and later, which can match multiple files with an expression. Some characters in the first field are escaped to match a single 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
# Makes all Perl files executable.
.*\.pl:x
The first field of a non-comment line is a file name or regular expression, without any leading path information, which refers to a file or directory in the same directory where the .tpattributes file exists. The file name is ended by a colon (which TFS 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 (like "link=$/Project/include") or a boolean attribute (like "x").
Teamprise supports the following attributes which can appear after the colon in a .tpattributes file. The descriptions specify which attributes may be combined.
A boolean attribute that means the named file should be made executable after being written to disk (files are normally not made executable; directories are). This attributes is only supported by Teamprise on Unix platforms (including Mac OS X) and may not be applied to directories. Teamprise will turn on the execute bits according to the user's umask. The x attribute may generally be combined with other attributes (certain exceptions apply).
When multiple files are matched by a regular expression, the executable attribute is applied to all files.
A string pair attribute that means a symbolic link should be created in place of the file name specified on this directive line. This file must exist in source 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" string pair attribute is a TFS server path (relative or absolute) that specifies where the symbolic link should point. Before Teamprise will create a symbolic link it checks to see if the link destination is mapped to a working folder in the current TFS workspace. If so, the link is created on disk to point to the item on disk. If the destination is not mapped, the symbolic link is not created because Teamprise can not determine where to point the link. The file contents from TFS 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.
This attribute is supported in Teamprise 3.3.
A string pair attribute that means a symbolic link should be created in place of the file name specified on this directive line. This file must exist in source 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" string pair attribute is a literal local path that specifies where the symbolic link should point. The local path is not interpreted by the Teamprise client; it is given to the operating system and may be any path style (relative or absolute) accepted by the operating system's symlink(2) function.
Like for the "link" attribute, when multiple files are matched by a regular expression, each file is created as a link to the link value.
"local-link" overrides the "link" attribute when 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.
This attribute is supported in Teamprise 3.1.1.
A string pair attribute 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 just 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. Only set this attribute for text files in encodings supported by your Java runtime. Setting this attribute for non-text files might result in corruption of the file contents.
The value of the "client-eol" string pair attribute is one of the following end-of-line styles:
| eol-style | Newline sequence used |
|---|---|
| lf | Unicode U+000A, used on Unix platforms including Mac OS X |
| crlf | Unicode U+000D,U+000A, used on Windows platforms |
| cr | Unicode U+000A, used on older Mac OS platforms (System 9 and previous) |
| native | the default style used on the platform where the Teamprise client is running |
Makefile: client-eol=native
build.sh: x | client-eol=lf
This attribute is supported in Teamprise 3.1.1.
A string pair attribute 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 just 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. Only set this attribute for text files in encodings supported by your Java runtime. Setting this attribute for non-text files might result in corruption of the file contents.
The value of the "server-eol" string pair attribute is one of the styles in the table shown above for the client-eol attribute.
win32-module.c: client-eol=native | server-eol=crlf
Makefile.MacOS9: server-eol=cr
This attribute is supported in Teamprise 3.1.1.
A string pair attribute that enabled automatic of conversion from a native file format on the client into a different format on the Team Foundation Server. The file will be transformed when it is sent to the server for a check-in or shelve operation, and will be transformed into its native format when it is retrieved from the server by a get operation.
The value of the "transform" string pair attribute is one of the following encoding techniques:
| transform | Encoding used |
|---|---|
| apple | This causes Mac OS-specific metadata to be preserved for 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. This option is only available on Teamprise clients on the Mac OS X platform. Other platforms will ignore this attribute. |
MacOS9Application: x | transform=apple
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 made into comments.