CLI Reference > Configuration Management Commands > si intro
 
si intro
introduction to reference pages
Description
A description of an individual topic (for example, a command) is loosely called the reference page for that topic, even if it is actually several pages long.
There are three alternatives for accessing the reference pages to each Integrity Lifecycle Manager configuration management command through the CLI man command.
First, you may simply type the si prefix and the command together as one word. Second, you may type the si prefix and the command with an underscore between them. Third, you may quote the si prefix and the command, with a space in the middle. For example:
man siabout
man si_about
man "si about" (Windows client only)
See the reference page for the man command itself, by typing man man, to find out more details.
This reference page describes the parts of a reference page with examples taken from real Integrity Lifecycle Manager reference pages.
The following sections discuss the various elements of a reference page.
Name
The Name section provides the name of the command and a brief functional description.
Synopsis
In the reference page for a command, the Synopsis section provides a quick summary of the command's format. For example, here is the synopsis of the si add command.
si add [--archive=filename] [--author=name] [(--binaryFormat|--textFormat)] [(--cpid=ID|--changePackageId=ID)] [--[no]defer] [--[no|confirm]closeCP] [--issueId=ID] [--description=desc] [--descriptionFile=file] [--issueId=ID] [(-l|--lock)] [--onExistingArchive=[confirm|sharearchive|newarchive|cancel]] [--[no]createSubprojects] [--[no]retainWorkingFile] [--[no]saveTimestamp] [--[no]unexpand] [(-r rev|--revision=rev)] [(-R |--[no|confirm]recurse)] [(-S sandbox|--sandbox=sandbox)] [--hostname=server] [--port=number] [--password=password] [--user=name] [--cwd=directory] [(-F file|--selectionFile=file)] [--forceConfirm=[yes|no]] [(-g|--gui)] [(-N|--no)] [--[no]batch] [--quiet] [--settingsUI=[gui|default]] [--status=[none|gui|default]] [(-?|--usage)] [(-Y|--yes)] [-R|--[no|confirm]recurse] [--[no|confirm]includeFormers] [--exclude=file:pattern,dir:pattern...] [--include=file:pattern,dir:pattern...] nonmember...
The synopsis takes the form of a command line as you might type it into the system; it shows what you can type in and the order in which you should do it. The parts that are enclosed in square brackets are optional; you may omit them if you choose. Parts that are not enclosed in square brackets must be present for the command to be correct.
The synopsis begins with the name of the command itself. The Integrity Lifecycle Manager configuration management commands all include the si prefix. In Integrity Lifecycle Manager documentation, command names are always written in bold Courier font.
After the command name comes a list of options. A typical Integrity Lifecycle Manager command option consists of either a single dash (-) followed by a single character, usually an uppercase or lowercase letter, or it may consist of a double dash (--) followed by a multi-character option name. Often there are single-character and multi-character options that do the same thing. The multi-character strings are not case sensitive, but are shown in mixed case to facilitate readability. For example, you might have -L or --label.
The synopsis line shows options in bold Courier font. Note that the case of single-character options is important; for example, in the synopsis of si add, -r and -R are different options, with different effects.
Furthermore, in the synopsis all options are shown in one long string. Other common option forms are:
-r rev
--revision=rev
where rev or, in some cases, value provides extra information for using that option. For example, the si lock command locks Sandbox members; here's the command's synopsis:
si lock [--[no|confirm]branch] [(--cpid=ID|--changePackageId=ID)] [--issueId=ID] [(-r rev|--revision=rev)] [(-R|--[no|confirm]recurse)] [--filter=filteroptions] [(-P project|--project=project)] [(-S sandbox|--sandbox=sandbox)] [--devpath=path] [--hostname=server] [--port=number] [--password=password] [--user=name] [(-?|--usage)] [(-F file|--selectionFile=file)] [(-N|--no)] [(-Y|--yes)] [--[no]batch] [--[no]recordAsWorkInProgress] [--[no|confirm]revisionMismatchIsError] [--cwd=directory] [--forceConfirm=[yes|no]] [(-g|--gui)] [--quiet] [--settingsUI=[gui|default]] [--status=[none|gui|default]] member...
In this example, there is the option
-r rev
This option tells the si lock command which revision to lock. In a command synopsis, anything appearing in italics is a placeholder for information that you are expected to supply. Sometime after the synopsis, the reference page explains what kind of information is expected in place of the placeholder.
The end of the si lock synopsis is
member...
Since there are no square brackets around the list, in this example, it is mandatory.
This means one or more member names; the ellipsis (...) stands for repetitions of whatever immediately precedes it. Most Integrity Lifecycle Manager commands allow you to specify lists of multiple items using spaces between them.
See the options reference page for more details on selecting members, Sandboxes and projects.
The order of items on the command line is important. When you type in a command line, you should specify the parts of the command line in the order they appear in the command synopsis. The exceptions to this are options marked with a - or a --; they do not have to be given in the exact order shown in the synopsis. However, all the - or -- options must appear in the correct area of the command line. For example, you can specify
si lock -r 1.2 --gui member1
si lock --gui -r 1.2 member1
but you will not get correct results if you specify
si lock member1 -r 1.2 --gui
si lock -r 1.2 member1 --gui
and so on.
Description
The Description section simply describes what the command does and how each option works.
Inside the Description section, the names of files and directories are written in normal Courier font. The names of environment variables are written in italic Courier font.
Diagnostics
The Diagnostics division contains information about the exit status returned by the command. You can test this status to determine the result of the operation the command was asked to perform.
See Also
The See Also section refers to other reference pages that may contain information relevant to the reference page you have just read.