docs/tf.txt

   1 tf(1)
   2 =====
   3
   4 NAME
   5 ----
   6 tf - Team Foundation Client
   7
   8
   9 SYNOPSIS
  10 --------
  11 'tf' [/server:<server name or ip address>] [/login:<login credentials>]
  12                 <command> [<command arguments>]
  13
  14 DESCRIPTION
  15 -----------
  16
  17 'tf' is a source control client for Microsoft Team Foundation Server.
  18
  19 OPTIONS
  20 -------
  21 */login:username [,password]*::
  22         Provide authentication credentials. If you don't specify a
  23   password you will be prompted for one. If you have
  24   gnome-keyring support enabled, TF will store the login
  25   credentials on your default keyring if configured to do so
  26         (see "Credentials.Save" configuration option below). The login username
  27   can be a domain account, in which case use the syntax "domain\\username".
  28
  29 */server:<server name or ip address>*::
  30         Specify the Team Foundation Server. If you are within a mapped
  31   working folder, you don't need to specify the /server option,
  32   as this information is stored in the VersionControl.config
  33   cache file.
  34
  35 COMMANDS
  36 --------
  37 *add <filenames>*::
  38         Pend an add on a file or files to the repository. To commit, you
  39   must issue a checkin command.
  40
  41 *changeset <changeset id>*::
  42         Show changeset details: committer, date, comment, and files changed.
  43         The changeset id is just an integer - no "C" prefix is required as in
  44         the diff command below.
  45
  46 *checkin [ <filenames or path> /recursive /comment:<comment> ]*::
  47         Checkin pending changes in workspace. With no arguments, this command
  48   will checkin all files in your workspace, not just all files underneath
  49   your current working directory. Due to a limitation in Mono.GetOptions,
  50   the /comment parameter cannot include spaces. This will be fixed soon!
  51
  52 *checkout <filenames>*::
  53   Checkout a file for editing. Command alias: edit.
  54
  55 *configure [ <key> | <key> <value> ]*::
  56         With no arguments, displays current configuration. With 1 argument,
  57         deletes the configuration setting <key>. With 2 arguments,
  58         sets the value of <key> to <value>. See Configuration section below
  59   for more details on valid settings.
  60
  61 *delete <filenames> [ /recursive ]*::
  62         Pend a delete against a file or files from the repository. To commit, you
  63   must issue a checkin command.
  64
  65 *diff [path | <changeset id> | <from versionSpec> <to versionSpec> path | /old | /modified ]*::
  66   Show pending changes as a diff. With /old, shows changes from current
  67   workspace to latest on the server as a diff. With /modified, shows
  68         changes to writable workspace files as a diff - another way to preview
  69         changes before using the *online* command. With a changeset id, like
  70   C12278, the command will show you a diff of the files changed in that
  71   changeset. With two version specs and a path, it will show the difference
  72   between those two versions for the specified path.
  73
  74 *dir <server path>*::
  75   List files in specified server path. A way to explore the folders on the server
  76   without setting up a workspace and downloading the files.
  77
  78 *explore*::
  79   Graphically explore a TF repository. Changeset view, directory view, and file view
  80   options. Control-C will copy currently selected path to the clipboard.
  81
  82 *get [ <path> ]*::
  83   Update local repository copy with latest versions from the server.
  84         Think "cvs/svn update". Note: Files are initially set to read-only, until
  85   checked out with the *checkout* command.
  86
  87 *help [ <cmd> | /list ]*::
  88   Show builtin help. Optionally, specify a tf command for which to
  89   show detailed help. The /list option is primarily a helper for shell
  90   completion code.
  91
  92 *history <filename | path > [ /format:<format> /recursive /stopafter:X ]*::
  93         Display changelog history for specified file. If you are looking for a
  94         git-log/svn log type function use this and add /recursive. Use /stopafter
  95   to limit the number of entries returned. Valid format specifiers include
  96         "brief" (the default), "detailed", and "byowner". The "detailed" format displays
  97         all files changed in a changeset and the "byowner" format summarizes the history
  98   by owner, showing how many changes each user committed.
  99
 100 *label <labelname> <itemspec> [ /recursive ]*::
 101   Add a label or tag to an item.
 102
 103 *labels [ <labelname> /owner:<ownername> /path:<server path> /format:detailed ]*::
 104         Displays labels or tags. Can optionally filter by <labelname>, <ownername>,
 105   and <serverpath>.
 106
 107 *lock /lock:[None | Checkin | Checkout] <itemspec> [ /recursive ]*::
 108         Locks a file in the repository. Use /lock:none to remove the lock.
 109
 110 *ls-files <path> [ /deleted | /modified | /old | /unknown ]*::
 111         Shows known, deleted, modified, old, or unknown files under the given path.
 112         With no options, ls-files shows known files. /old option by default shows
 113   only files in your workspace which are out of date, not new files on the
 114   server you've not yet fetched. To show those files as well, use "/old /all".
 115   This behavior may change in future releases, based on user feedback.
 116
 117 *merges [<source>] <destination>*::
 118         Lists merge points in the history of the destination item. The destination
 119         item can either be expressed as a server item or a local item.
 120
 121 *online <path> [ /added | /modified | /deleted | /preview ]*::
 122   Finds all writable files and marks them as pending changes on the server.
 123         It also finds all unknown files and marks them as pending adds, missing
 124   files are marked as pending deletes. A great command to use if you apply
 125         a patch to a clean tfs-managed tree and want to pend the changes to the
 126         server for checkin. The /added, /modified, /deleted flags can be used
 127         to show just additions, just modifications, or just deletions respectively.
 128         These flags may be combined. With no flags, all changes are shown.
 129
 130 *perm <filename>*::
 131         Show server permissions on a file. Command alias: permission.
 132
 133 *properties <filenames> [ /recursive ]*::
 134         Show detailed properties for each filename including server locks, encoding,
 135   last modified date, changeset id, and whether the file has a newer version
 136   on the server.
 137
 138 *rename <oldname> <newname>*::
 139         Rename a file or files in the repository.
 140
 141 *rollback <changeset>*::
 142         Undo a changeset. Retrieves previous versions of all files modified
 143         in the selected changeset, then marks them as pending changes. NOTE:
 144         this command is only useful if no one else has changed the file since
 145         <changeset> was checked in. If a file has been modified by subsequent
 146         checkins and you rollback, all subsequent modifications will be lost!
 147
 148 *shelve <name> [ <path> | /delete ]*::
 149         Create or delete a shelveset. A shelveset is a way to store local changes
 150   on the server without checking them in.
 151
 152 *shelvesets [ <name> | <name;owner> ] [ /owner:<owner> ]*::
 153   Show shelvesets on the server. Use /owner:"*" and no name argument to view all
 154   shelvesets.
 155
 156 *show [ build | cache | ident | stats | tools ]*::
 157         Show information about build configuration, cache settings, identity info,
 158         usage statistics, or registered server tools.
 159
 160 *status [ <filenames> /recursive ]*::
 161   Show status of all pending changes in local workspace. Optional paths/filenames
 162         may be added to narrow the resulting output.
 163
 164 *treeclean*::
 165   Delete all files not under version control. Use /preview to see what
 166         would be deleted.
 167
 168 *undo [ <filenames> /recursive ]*::
 169   Undo pending changes. With no filenames, undoes all pending changes.
 170
 171 *unlabel <labelname> <itemspec>*::
 172   Remove a label or tag from an item.
 173
 174 *workspace [ /new | /delete ]*::
 175   Manage workspaces.
 176
 177 *workspaces [ /format:detailed <workspace-name> ]*::
 178         List workspaces in server repository. Use /format:detailed for additional
 179   information. Specify a workspace name to filter results.
 180
 181 *workfold [ <server path> <local path> | /unmap <local path> ]*::
 182   Manage working folders. With no arguments, print current working folder
 183   mappings. With a server path and local path, creates a new working folder
 184   mapping.
 185
 186 *version*::
 187   Displays the version of the program.
 188
 189 *view <filenames | server paths>*::
 190         Displays the latest version of the specified file or files.
 191
 192 EXAMPLES
 193 --------
 194
 195 *List all workspaces on the server 10.2.10.2, using a username of "domain\\username" and a password of "password".*::
 196   tf workspaces /server:10.2.10.2 /login:domain\\username,password /owner:"+++*+++" /computer:"+++*+++"
 197
 198 *Create a workspace with the name "workspaceName" with an owner name of ownerName.*::
 199   tf workspace /new "workspaceName;ownerName"
 200
 201 *Setup a working folder for the project "ProjectName" in directory ~/src/project.*::
 202   tf workfold "$/ProjectName" /home/username/src/project
 203
 204 *Fetch/Get all files in folder in project "ProjectName" to local machine.*::
 205   tf get /recursive /home/username/src/project
 206
 207 *Delete the workspace "workspaceName" created above.*::
 208  tf workspace /delete workspaceName
 209
 210 *Add all unknown files to the repository.*::
 211  tf ls-files /others %% add
 212
 213 MULTIPLE COMMANDS
 214 -----------------
 215 You can execute multiple commands in sequence in a single run of TF,
 216 by separating the commands with '%'. Here's how you might checkin a
 217 patch with a single run of TF:
 218
 219
 220 ------------
 221 $  patch -p1 < ~/new-feature.diff
 222 $  tf online % checkin
 223 ------------
 224
 225 If you'd like to pipe the output from the ls-files or diff (brief
 226 mode only) subcommands to the next subcommand in the chain use
 227 '%%' instead. This can be particularly useful with ls-files.
 228
 229 CONFIGURATION
 230 -------------
 231 The TF client stores configuration settings in ~/.tf/TfClient.config.
 232
 233 *Checkin.Validate*::
 234         The TF client will display a summary of pending
 235   changes and ask for confirmaton below committing changes to the server
 236   when set to "true". The default is "false". It's non-trivial to rollback
 237   a committed change, so this option is highly recommended.
 238
 239 *Checkout.Latest*::
 240   The TF client will always checkout the latest version rather than
 241   the workspace version if this setting is set to "true". Note: this option
 242         only effects the checkout command, not the "online" command.
 243
 244 *Credentials.Save*::
 245         The TF client will store login credentials if this
 246   setting is set to "true". The default is "false".
 247
 248 *File.Excludes*::
 249         A comma separated list of files to ignore. Currently, only the "online"
 250         command honors this setting. The wildcard characters * and ? are supported.
 251         Example setting: "*.dll,*.pdb".
 252
 253 *File.ReadWrite*::
 254   The TF client defaults to setting all non-checked out files to readonly. Set
 255   this setting to "true" to make them read-write.
 256
 257 *Get.DefaultToCwd*::
 258         The TF client will default to updating all registered working folders if no
 259         folder arguments are given when running the subcommand "get". By enabling
 260         this option, the TF client will instead look for updates starting with
 261         the current working folder and subfolders (as needed). If you have lots of
 262         registered working folders but only actively track a few of these folders,
 263         the default behavior can become quite tedious.
 264
 265 *Get.ChangesetMtimes*::
 266   The TF client does not default to preserving file modification times. By
 267         enabling this option, TF will set the modification time of any file
 268         subsequently fetched to the date of the last changeset in which the file
 269         was modified. Warning: this mode of operation can significantly slow down
 270   "tf get".
 271
 272 *Get.Recursive*::
 273         The TF client will automatically do recursive gets when set
 274         to "true". IMHO, this is far more useful than the default       behavior.
 275
 276 *History.Detailed*::
 277         The TF client defaults to brief output of history which does not include
 278         file level information. Set this setting to "true" to get file level history.
 279
 280 *History.DefaultToCwd*::
 281         The TF client will default to the current working directory if not options
 282         are given when running the subcommand "history". The default behavior of the
 283         standard client is to require a path for all history queries. This option
 284   provides an optional and more sensible default.
 285
 286 *History.Recursive*::
 287         The TF client will automatically do recursive history queries when set
 288         to "true". IMHO, this is far more useful than the default       behavior.
 289
 290 *History.StopAfter*::
 291   The TF client defaults to showing the last 255 checkins in history output.
 292   Set this option to an integer to change the default.
 293
 294 *Merges.Recursive*::
 295         The TF client will automatically do recursive merge queries when set
 296         to "true". IMHO, this is far more useful than the default       behavior.
 297
 298 *Online.Recursive*::
 299         The TF client will automatically do a recursive online command when set
 300         to "true". IMHO, this is far more useful than the default       behavior for
 301         clean trees. Not as helpful for trees littered with build output files.
 302
 303 *Server.Default*::
 304   If the TF client cannot determine the server to connect to, first from
 305         the "/server:" option, and second the workspace cache, then it will
 306   use the Server.Default setting if non-null.
 307
 308 *Workfold.CreateLocal*::
 309         When you map a local directory to a server path, the TF client does not
 310         automatically create the local directory. Enable this option to do so.
 311
 312 *Workspace.Default*::
 313   If the TF client cannot determine the active workspace, first from
 314         the "/workspace:" option, and second the workspace cache, then it will
 315   use the Workspace.Default setting if non-null.
 316
 317 WORKSPACE CACHE
 318 ---------------
 319 The TF client keeps a cache of workspaces and folder mappings in
 320 ~/.tf/Cache/VersionControl.config. Here's a sample file:
 321
 322 The contents of the cache can be seen with the *tf cache* command.
 323
 324 ------------
 325 <VersionControlServer>
 326   <Servers>
 327     <ServerInfo uri="http://10.2.1.2:8080/">
 328       <WorkspaceInfo name="neo" ownerName="DOMAIN\USER" computer="MYBOX" comment="" LastSavedCheckinTimeStamp="4/26/2007 11:55:50 PM">
 329         <MappedPaths>
 330           <MappedPath path="/home/jreed/Source/xyz-project" />
 331           <MappedPath path="/home/jreed/Source/abc-project" />
 332         </MappedPaths>
 333       </WorkspaceInfo>
 334     </ServerInfo>
 335   </Servers>
 336 </VersionControlServer>
 337 ------------
 338
 339
 340 IMPLEMENTATION NOTES
 341 --------------------
 342 TFS doesn't have built in support for tracking file attributes, for
 343 example, whether the file is executable or not. The TF client included
 344 in this package makes use of libmagic to determine whether a file
 345 should be marked executable or not.
 346
 347
 348 MORE INFORMATION
 349 ----------------
 350 http://groups.google.com/group/opentf
 351 http://msdn2.microsoft.com/en-us/library/bb130146(VS.80).aspx
 352 http://msdn2.microsoft.com/en-us/teamsystem/default.aspx
 353 http://msdn2.microsoft.com/en-us/cc31bk2e(VS.80).aspx
 354
 355
 356 AUTHOR
 357 ------
 358 Written by Joel Reed <joelwreed@gmail.com>
 359
 360
 361 DOCUMENTATION
 362 --------------
 363 Documentation by Joel Reed <joelwreed@gmail.com>
 364