icon.repo
[tfs.git] / docs / tf.txt
blob7723f507b92130f282e2b22d23aa5d6d799d60f0
1 tf(1)
2 =====
4 NAME
5 ----
6 tf - Team Foundation Client
9 SYNOPSIS
10 --------
11 'tf' [/server:<server name or ip address>] [/login:<login credentials>]
12                 <command> [<command arguments>]
14 DESCRIPTION
15 -----------
17 'tf' is a source control client for Microsoft Team Foundation Server.
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".
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.
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. 
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.
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!
52 *checkout <filenames>*::
53   Checkout a file for editing. Command alias: edit.
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.
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.
65 *diff <filename or path or changeset id> [ /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.
73 *dir <server path>*::
74   List files in specified server path. A way to explore the folders on the server
75   without setting up a workspace and downloading the files.
77 *explore*::
78   Graphically explore a TF repository. Changeset view, directory view, and file view
79   options. Control-C will copy currently selected path to the clipboard.
81 *get [ <path> ]*::
82   Update local repository copy with latest versions from the server. 
83         Think "cvs/svn update". Note: Files are initially set to read-only, until
84   checked out with the *checkout* command.
86 *help [ <cmd> | /list ]*::
87   Show builtin help. Optionally, specify a tf command for which to 
88   show detailed help. The /list option is primarily a helper for shell 
89   completion code.
91 *history <filename | path > [ /format:<format> /recursive /stopafter:X ]*::
92         Display changelog history for specified file. If you are looking for a
93         git-log/svn log type function use this and add /recursive. Use /stopafter
94   to limit the number of entries returned. Valid format specifiers include 
95         "brief" (the default), "detailed", and "byowner". The "detailed" format displays
96         all files changed in a changeset and the "byowner" format summarizes the history
97   by owner, showing how many changes each user committed.
99 *label <labelname> <itemspec> [ /recursive ]*::
100   Add a label or tag to an item.
102 *labels [ <labelname> /owner:<ownername> /format:detailed ]*:: 
103         Displays labels or tags. Can optionally filter by <labelname> and <ownername>.
105 *lock /lock:[None | Checkin | Checkout] <itemspec> [ /recursive ]*::
106         Locks a file in the repository. Use /lock:none to remove the lock.
108 *ls-files <path> [ /deleted | /modified | /old | /unknown ]*::
109         Shows known, deleted, modified, old, or unknown files under the given path.
110         With no options, ls-files shows known files. /old option by default shows
111   only files in your workspace which are out of date, not new files on the
112   server you've not yet fetched. To show those files as well, use "/old /all".
113   This behavior may change in future releases, based on user feedback.
115 *online <path> [ /added | /modified | /deleted | /preview ]*::
116   Finds all writable files and marks them as pending changes on the server.
117         It also finds all unknown files and marks them as pending adds, missing
118   files are marked as pending deletes. A great command to use if you apply
119         a patch to a clean tfs-managed tree and want to pend the changes to the 
120         server for checkin. The /added, /modified, /deleted flags can be used
121         to show just additions, just modifications, or just deletions respectively.
122         These flags may be combined. With no flags, all changes are shown.
124 *perm <filename>*::
125         Show server permissions on a file. Command alias: permission.
127 *properties <filenames> [ /recursive ]*::
128         Show detailed properties for each filename including server locks, encoding,
129   last modified date, changeset id, and whether the file has a newer version
130   on the server.
132 *rename <oldname> <newname>*::
133         Rename a file or files in the repository.
135 *shelve <name> [ <path> | /delete ]*::
136         Create or delete a shelveset. A shelveset is a way to store local changes
137   on the server without checking them in.
139 *shelvesets [ <name> | <name;owner> ] [ /owner:<owner> ]*::
140   Show shelvesets on the server. Use /owner:"*" and no name argument to view all 
141   shelvesets.
143 *show [ build | cache | ident | stats | tools ]*:: 
144         Show information about build configuration, cache settings, identity info,
145         usage statistics, or registered server tools.
147 *status [ <filenames> /recursive ]*::
148   Show status of all pending changes in local workspace. Optional paths/filenames
149         may be added to narrow the resulting output.
151 *treeclean*::
152   Delete all files not under version control. Use /preview to see what 
153         would be deleted.
155 *undo [ <filenames> /recursive ]*::
156   Undo pending changes. With no filenames, undoes all pending changes.
158 *unlabel <labelname> <itemspec>*::
159   Remove a label or tag from an item.
161 *workspace [ /new | /delete ]*::
162   Manage workspaces.
164 *workspaces [ /format:detailed <workspace-name> ]*::
165         List workspaces in server repository. Use /format:detailed for additional
166   information. Specify a workspace name to filter results.
168 *workfold [ <server path> <local path> | /unmap <local path> ]*::
169   Manage working folders. With no arguments, print current working folder 
170   mappings. With a server path and local path, creates a new working folder
171   mapping.
173 *version*::
174   Displays the version of the program.
176 *view <filenames | server paths>*::
177         Displays the latest version of the specified file or files.
179 EXAMPLES
180 --------
182 *List all workspaces on the server 10.2.10.2, using a username of "domain\\username" and a password of "password".*::
183   tf workspaces /server:10.2.10.2 /login:domain\\username,password /owner:"+++*+++" /computer:"+++*+++"
185 *Create a workspace with the name "workspaceName" with an owner name of ownerName.*::
186   tf workspace /new "workspaceName;ownerName"
188 *Setup a working folder for the project "ProjectName" in directory ~/src/project.*::
189   tf workfold "$/ProjectName" /home/username/src/project
191 *Fetch/Get all files in folder in project "ProjectName" to local machine.*::
192   tf get /recursive /home/username/src/project
194 *Delete the workspace "workspaceName" created above.*::
195  tf workspace /delete workspaceName
197 *Add all unknown files to the repository.*::
198  tf ls-files /others %% add
200 MULTIPLE COMMANDS
201 -----------------
202 You can execute multiple commands in sequence in a single run of TF, 
203 by separating the commands with '%'. Here's how you might checkin a 
204 patch with a single run of TF:
207 ------------
208 $  patch -p1 < ~/new-feature.diff
209 $  tf online % checkin
210 ------------
212 If you'd like to pipe the output from the ls-files or diff (brief
213 mode only) subcommands to the next subcommand in the chain use
214 '%%' instead. This can be particularly useful with ls-files.
216 CONFIGURATION
217 -------------
218 The TF client stores configuration settings in ~/.tf/TfClient.config.
220 *Checkin.Validate*::
221         The TF client will display a summary of pending
222   changes and ask for confirmaton below committing changes to the server
223   when set to "true". The default is "false". It's non-trivial to rollback
224   a committed change, so this option is highly recommended.
226 *Checkout.Latest*::
227   The TF client will always checkout the latest version rather than
228   the workspace version if this setting is set to "true". Note: this option
229         only effects the checkout command, not the "online" command.
231 *Credentials.Save*:: 
232         The TF client will store login credentials if this
233   setting is set to "true". The default is "false".
235 *File.Excludes*::
236         A comma separated list of files to ignore. Currently, only the "online"
237         command honors this setting. The wildcard characters * and ? are supported.
238         Example setting: "*.dll,*.pdb".
240 *File.ReadWrite*::
241   The TF client defaults to setting all non-checked out files to readonly. Set
242   this setting to "true" to make them read-write.
244 *Get.DefaultToCwd*::
245         The TF client will default to updating all registered working folders if no
246         folder arguments are given when running the subcommand "get". By enabling
247         this option, the TF client will instead look for updates starting with
248         the current working folder and subfolders (as needed). If you have lots of
249         registered working folders but only actively track a few of these folders,
250         the default behavior can become quite tedious.
252 *Get.Recursive*::
253         The TF client will automatically do recursive gets when set
254         to "true". IMHO, this is far more useful than the default       behavior.
256 *History.Detailed*::
257         The TF client defaults to brief output of history which does not include 
258         file level information. Set this setting to "true" to get file level history.
260 *History.DefaultToCwd*::
261         The TF client will default to the current working directory if not options
262         are given when running the subcommand "history". The default behavior of the
263         standard client is to require a path for all history queries. This option
264   provides an optional and more sensible default.
266 *History.Recursive*::
267         The TF client will automatically do recursive history queries when set
268         to "true". IMHO, this is far more useful than the default       behavior.
270 *History.StopAfter*::
271   The TF client defaults to showing the last 255 checkins in history output.
272   Set this option to an integer to change the default.
274 *Online.Recursive*::
275         The TF client will automatically do a recursive online command when set
276         to "true". IMHO, this is far more useful than the default       behavior for
277         clean trees. Not as helpful for trees littered with build output files.
279 *Server.Default*::
280   If the TF client cannot determine the server to connect to, first from 
281         the "/server:" option, and second the workspace cache, then it will
282   use the Server.Default setting if non-null.
284 *Workspace.Default*::
285   If the TF client cannot determine the active workspace, first from 
286         the "/workspace:" option, and second the workspace cache, then it will
287   use the Workspace.Default setting if non-null.
289 WORKSPACE CACHE
290 ---------------
291 The TF client keeps a cache of workspaces and folder mappings in 
292 ~/.tf/Cache/VersionControl.config. Here's a sample file:
294 The contents of the cache can be seen with the *tf cache* command.
296 ------------
297 <VersionControlServer>
298   <Servers>
299     <ServerInfo uri="http://10.2.1.2:8080/">
300       <WorkspaceInfo name="neo" ownerName="DOMAIN\USER" computer="MYBOX" comment="" LastSavedCheckinTimeStamp="4/26/2007 11:55:50 PM">
301         <MappedPaths>
302           <MappedPath path="/home/jreed/Source/xyz-project" />
303           <MappedPath path="/home/jreed/Source/abc-project" />
304         </MappedPaths>
305       </WorkspaceInfo>
306     </ServerInfo>
307   </Servers>
308 </VersionControlServer>
309 ------------
312 IMPLEMENTATION NOTES
313 --------------------
314 TFS doesn't have built in support for tracking file attributes, for
315 example, whether the file is executable or not. The TF client included 
316 in this package makes use of libmagic to determine whether a file 
317 should be marked executable or not.
320 MORE INFORMATION
321 ----------------
322 http://groups.google.com/group/opentf
323 http://msdn2.microsoft.com/en-us/library/bb130146(VS.80).aspx
324 http://msdn2.microsoft.com/en-us/teamsystem/default.aspx
325 http://msdn2.microsoft.com/en-us/cc31bk2e(VS.80).aspx
328 AUTHOR
329 ------
330 Written by Joel Reed <joelwreed@gmail.com>
333 DOCUMENTATION
334 --------------
335 Documentation by Joel Reed <joelwreed@gmail.com>