NEWLABEL labels a directory in the version-control system. The new label is always an AbaPerls label on the format LetterMajor.Middle.Minor, for instance L2.63.0120. NEWLABEL also enforces that the new label has the same Major and Middle components as previous labels, and that Minor is greater than any earlier label.

   Command-line syntax
   Notes for TFS

Command-line syntax

newlabel [-update] VC-path [ label | letter | [letter]minor | +[letter]increment ]

NEWLABEL takes two arguments. The first argument specifies the path to label, and the second argument specifies the new label which can be expressed in a number of ways. By default, NEWLABEL runs in read-only mode where it computes the new label, prints it and exit. To actually label the directory, you need to use the ‑update option.

VC-path is a path in the version-control system, following the standard conventions for version-control paths in AbaPerls. Normally, the path includes a version number component on the form Major.Middle, for instance TFS::MYTFS/$/TeamProject/2.63/Component. In this example, 2.63 is the version number. There must not be two possible version numbers in the path. If you specify a path without version number, NEWLABEL derives the version from the existing labels for the directory. In this case, all labels must have the same Major.Middle. If there are no existing labels at all, you will need to set the first label manually through the tools provided by the version-control system.

The new label can be specified in a number of ways:

(nothing)If you don't specify a label argument at all, the next label will be derived by adding 10 to the most recent label, rounding down to the nearest 10, using the same prefix. That is, if the most recent label is L2.63.0200 the next label will be L2.63.0010. If the most recent label is A4.20.0211, the next label will be A4.20.0220.
letter If you specify a single letter and nothing more, this works the same way as when you specify nothing at all, but the new label will start with letter rather than inheriting the letter from a previous label. For instance, the most recent label is L5.30.1230, and you specify F for the second argument. The new label is F5.30.1240.
+[letter]incrementIf you specify a string starting with a plus character, followed by a number with an optional single letter in between, this specifies an increment to the most recent label. The prefix letter is inherited from the previous label, unless you specify a new letter. If the increment is equally divisible by 10, the new label will be rounded down to the nearest 10. Assume that the most recent label is L4.20.0211. If you specify +90, the new label is L4.20.0300. If you specify +13, the new label is L4.20.0224. If you specify +M90, the new label is M4.20.0300.
[letter]minor If you specify a number, optionally preceded by a single letter, this implies an explicit number for Minor in the new label. NEWLABEL pads the number, so there are at least 4 digits in Minor. Minor must be numerically greater than the minor part of the most recent label. Assume that the most recent label is G6.30.0040. If you specify 45, the new label is G.6.30.0045. If you specify L100, the new label is L6.30.0100. If you specify 20 or L20, this is an error.
label You can specify a complete label on the AbaPerls format LetterMajor.Middle.Minor. If there is a version number in VC-path, Major.Middle of label must match that version number. The minor part must be numerically greater than the most recent label for the directory. Examples: VC-path is $/Test/2.05, and the most recent label is L2.05.0200. L2.05.0280 is a legit value, whereas illegal values are L2.10.0280 (version directory not matching) and L2.05.0180 (Minor less than Minor for most recent label). NEWLABEL pads the middle part to two digits, and the minor part to four digits, so if you specify the label as L2.5.210, the new label will be L2.05.0210.

When looking for labels, AbaPerls only considers labels that adhere to the AbaPerls format of LetterMajor.Middle.Minor. Furthermore, if there is a version number in VC-path, NEWLABEL only considers labels that match that version number. That is, if VC-path is $/Test/2.05, and there are the labels MyLabel and L2.04.2000, AbaPerls ignores these labels.

If there are no matching labels at all, AbaPerls assumes a label with the letter L and a minor part of 0. Thus if you label $/Demo/1.0 and there is no previous label, and you don't specify any second argument to NEWLABEL, the new label will be L1.00.0010.

If the old minor part is < 1000, the new minor part must also be < 1000, to comply with the rules implied by NEWSUBSYSVER. However, see the coming example of a situation when AbaPerls does not enforce this.

AbaPerls looks for matching labels both above and below in the hierarchy. Assume that you have three subsystems below a common version number: $/product/10.50/A with the most recent label A10.50.0050, $/product/10.50/B with the most recent label B10.50.0080 and $/product/10.50/C with the most recent label C10.50.2000, and you say

newlabel $/product/10.50 L

In this case you will label all three subsystems with the label L10.50.2010. That is, the label for C is the most recent label. Note here AbaPerls does not enforce the 1000 rule for the subsystems A and B here.

If you later say

newlabel $/product/10.50/A

The new label for A will be L10.50.2020.

Notes for TFS

When the version-control system is TFS, NEWLABEL writes the current time (with time-zone) as a comment for the label. In situations when AbaPerls needs to know when the label was set, AbaPerls will read this value if it is available, rather than the date for the label in TFS. This is because TFS does not save the creation date, only the date when the label was most recently modified.

Labels in TFS have scopes, but when you label from Visual Studio, the scope is always global, meaning that this label cannot be created anew somewhere else in the team project. That is, if you right-click  $/product/10.50/A, and set the label L10.50.0020, and later right-click $/product/10.50/B and specify L10.50.0020 as the label, you will edit the existing label and not set a new label.

When you use NEWLABEL, the scope is always the same as the directory that you specify. In some screens, TFS displays the scope appended to the label, with @ as a separator. For instance, L10.50.20@$/product/10.50/A.

If you mistakenly set an AbaPerls label through Team Explorer in Visual Studio, you can correct the scope with help of the tool TFSLABELFIX.