|
|
<HTML><HEAD><TITLE>sdv</TITLE><STYLE><!--BODY, TABLE { font-family: Arial; font-size: 10pt; }PRE, CODE { font-family: Lucida Console; }PRE I { font-family: Arial; }--></STYLE></HEAD><BODY>
<H1>sdv</H1>
<P>A GUI front-end to some Source Depot commands.
<ul><li><a href=#cmdli>Command line syntax</a> <ul> <li><a href=#chang>sdv changes</a> <li><a href=#descr>sdv describe</a> <li><a href=#filel>sdv filelog</a> <li><a href=#opene>sdv opened</a> <li><a href=#short>Shortcuts</a> </ul><li><a href=#troub>Troubleshooting</a><li><a href=#branc>sdv branch syntax</A><li><a href=#psych>sdv special powers</A><li><a href=#limit>Limitations</a><li>Appendix <ul> <li><a href=#ntbrn>Windows NT branch model</A> </ul></ul>
<H2><A NAME=cmdli>Command line syntax</a></H2>
<PRE>sdv [ options ] command [ arg ... ]</PRE>
<P>Some options are common to all sdv commands.Note that all common options begin with a double-dash andthey come <STRONG>before</STRONG> the command name.
<DL><DT><CODE>--s "</CODE><I>sdoptions</I><CODE>"</CODE><DD><P>Pass <I>sdoptions</I> directly to sd. See "sd help usage" for details on sd options. If you need to pass quotation marks to sd, use double quotation marks. <P> Examples:<PRE>sdv --s "-p server:4001"sdv --s "-P ""my password"""</PRE> <P> Note: sdv does not parse these options. It passes them blindly to sd. The intent of this flag is to allow you to provide access/authentication information. Passing an option that alters sd's behavior in a more substantial way (such as the -V option) will result in sdv getting extremely confused. </P>
<DT><CODE>--#</CODE><DD><P>Enables computation of "code churn" statistics. If enabled, reports will include churn information in the form "deleted/added". For example, a churn value of "5/3" means that five lines were deleted and three lines were added. <STRONG>Requires sd 1.5</STRONG>. <P> Note: Computing churn is expensive, so it's off by default. <P>
</DL>
<H3><A NAME=chang>sdv changes</a></H3>
<PRE>sdv [ options ] changes [-i] [-m [skip,]count] [-u userid] [ pattern ... ]</PRE>
<P>Display the results of an "sd changes" command.
<DL><DT><I>options</I><DD><P><a href=#cmdli>Common sdv options</a> are supported. </P>
<DT><CODE>-i</CODE><DD><P>Has the same effect as the "sd changes -i" option. </P>
<DT><CODE>-m</CODE><I>skip,count</I><DD><P>Has the same effect as the "sd changes -m" option. If no "-m" flag is provided, sdv defaults to "-m50". </P>
<DT><CODE>-u</CODE> <I>userid</I><DD><P>Has the same effect as the "sd changes -u" option. <STRONG>Requires sd 1.6; is emulated on previous versions of sd</STRONG>. </P>
<DT><I>pattern</I><DD><P>Zero or more patterns. </P></DL>
<P>sdv supports the same patterns as sd, with the following differences:</P>
<UL><LI><P>The default pattern is "*" (all files in current directory) rather than "all files in the depot". To query against all files in the depot, use<PRE> sdv changes ""</PRE> to force a null query string to be passed to sd. </P>
<LI><P><A href=#branc>sdv branch syntax</A> is supported. </P></UL>
<P>To view the details of a particular changelist, double-click it.This will open a changelist view.
<P>Hovering over a change number displays the full change descriptionas an infotip.
<P>The "Comment" field is the first line of the checkin description.So make it a good one!
<P>To see what else you can do, right-click a change number orbrowse the menus.
<H3><A NAME=descr>sdv describe</a></H3>
<PRE>sdv [ options ] describe changeno [ pattern ... ]</PRE>
<P>Display the results of an "sd describe" command.
<DL><DT><I>options</I><DD><P><a href=#cmdli>Common sdv options</a> are supported. </P>
<DT><I>changeno</I><DD><P>The change list to display. </P>
<DT><I>pattern ...</I><DD><P>Optional list of patterns for files that should be moved to the top of the file list. This is provided for scripting; you are not expected to pass patterns manually. </P>
</DL>
<P>From the changelist description, you can double-click the first line(the one that begins "Change 1234")to view the entire changelist in windiff.Alternatively, you can double-click aspecific file to view the diff for only that file.
<P>You can type Ctrl+C (or for old-timers, Ctrl+Insert) to copya line from the changelist view to the clipboard. If you copya line from the file list, then the full depot specificationand the revision number are copied. All other lines are copiedverbatim.
<P>If churn is enabled, each text file that was edited will have thechurn values appended.
<P>Files which match the pattern (or which are connected to filesmatching the pattern via a chain of branch integrations) areplaced at the top of the file list.<STRONG>Note: Assumes Windows NT branch model</STRONG>.
<P>If the describe window was opened from another sdv window,the donor sdv window will set a pattern that causes the filesit thinks you are interested in to go to the top of the file list.
<P>If churn is enabled, then files with a churn of (0/0) are droppedto the bottom of the list, since they are rarely interesting.
<P>To see what else you can do, right-click a line of the changelistdescription or browse the menus.
<H3><A NAME=filel>sdv filelog</a></H3>
<PRE>sdv [ options ] filelog [-# revision] [-m [skip,]count] file[revRange]</PRE>
<P>Display the results of an "sd filelog" command.
<DL><DT><I>options</I><DD><P><a href=#cmdli>Common sdv options</a> are supported. </P>
<DT><I><CODE>-#</CODE> revision</I><DD><P>Optional revision number to autoselect in the results window. If no "-m" flag is provided, sdv autoselects the most recent revision. This is provided for scripting; you are not expected to specify an autoselect revision when running sdv manually. </P>
<DT><CODE>-m</CODE><I>skip,count</I><DD><P>Has the same effect as the "sd filelog -m" option. If no "-m" flag is provided, sdv shows all revisions. </P>
<DT><I>file[revRange]</I><DD><P>The file whose log is to be viewed, optionally restricted with a revision range. <A href=#branc>sdv branch syntax</A> is supported for this parameter. Wildcards are not permitted here; you can view the filelog for only one file at a time. </P>
</DL>
<P>From the filelog, you can double-click aspecific revision to view the diff for that change.
<P>If churn is enabled, each text file that was edited will have thechurn values appended.
<P>To see what else you can do, right-click a line of the filelogor browse the menus.
<H3><A NAME=opene>sdv opened</a></H3>
<PRE>sdv [ options ] opened [ -u domain\user ] [ file ... ]</PRE>
<P>Display the opened files on the client, grouped by changelist.
<DL><DT><I>options</I><DD><P><a href=#cmdli>Common sdv options</a> are supported. </P>
<DT><CODE>-u</CODE> <I>domain\user</I><DD><P>Optional user whose opened files on the client are to be viewed. Default is the current user. </P>
<DT><I>file ...</I><DD><P>Optional list of files to display. Default is to show all opened files. </P>
</DL>
<P>To see what you can do, right-click a line of the listor browse the menus.
<H3><A NAME=short>Shortcuts</a></H3>
<P>If the command line to sdv does not match one of the patterndescribed above, then sdv attempts to guess which command youare trying to execute.</P>
<TABLE><TR><TD><B>You type</B></TD><TD WIDTH=20></TD> <TD><B>Implied command</B></TD><TD WIDTH=20></TD> <TD><B>Equivalent to</B></TD></TR><TR><TD>sdv 1234</TD><TD></TD><TD>describe</TD><TD></TD><TD>sdv describe 1234</TD></TR><TR><TD>sdv file</TD><TD></TD><TD>filelog</TD><TD></TD><TD>sdv filelog file</TD></TR><TR><TD>sdv pattern*.c*</TD><TD></TD><TD>changes</TD><TD></TD><TD>sdv changes pattern*.c*</TD></TR><TR><TD>sdv -i .../pattern</TD><TD></TD><TD>changes</TD><TD></TD><TD>sdv changes -i .../pattern</TD></TR><TR><TD>sdv</TD><TD></TD><TD>changes</TD><TD></TD><TD>sdv changes</TD></TR></TABLE>
<P>Note that these heuristics are not robust. For example, if youhave a file called "1234", then "sdv 1234" will be interpretedas "sdv describe 1234" and not"sdv filelog 1234".Or if youhave a file called "changes", then "sdv changes" will be interpretedas "sdv changes" with no arguments rather than as"sdv filelog changes".
<P>To avoid these problems, just give the command explicitlyinstead of relying on a shortcut.
<H2><A NAME=troub>Troubleshooting</A></H2>
If you get an error from windiff saying that it doesn't supportdepot paths on the command line, then you need a newer versionof windiff.
<H2><A NAME=branc>sdv branch syntax</A></H2>
<P>sdv supports an enhancement to the standard sd file specificationsto allow easy navigation of branches.<STRONG>Note: Assumes your depot follows the Windows NT branch model</STRONG>.
<P>If you prefix a pattern witha branch name and a colon, the file is reinterpreted to come fromthe specified branch rather than from the current directory.If the branch name begins with a slash, then the branch name isa private branch. Otherwise, it is a top-level (official) branch.
<P>(Branch names must be at least two characters long to prevent thebranch syntax from being misinterpreted as a drive letter.)
<P>The following examples assume that the current directory correspondsto //depot/exp/sdv.</P>
<TABLE><TR><TD><B>Pattern</B></TD><TD WIDTH=20></TD><TD><B>Expands to</B></TD></TR><TR><TD>sdv.h</TD><TD></TD><TD>//depot/exp/sdv/sdv.h</TD></TR><TR><TD>main:sdv.h</TD><TD></TD><TD>//depot/main/sdv/sdv.h</TD></TR><TR><TD>/office:sdv.h</TD><TD></TD><TD>//depot/private/office/sdv/sdv.h</TD></TR>
<TR><TD COLSPAN=3> </TD></TR>
<TR><TD>...</TD><TD></TD><TD>//depot/exp/sdv/...</TD></TR><TR><TD>main:...</TD><TD></TD><TD>//depot/main/sdv/...</TD></TR><TR><TD>/office:...</TD><TD></TD><TD>//depot/private/office/sdv/...</TD></TR>
<TR><TD COLSPAN=3> </TD></TR>
<TR><TD>../bbpack/*.cmd</TD><TD></TD><TD>//depot/exp/bbpack/*.cmd</TD></TR><TR><TD>main:../bbpack/*.cmd</TD><TD></TD><TD>//depot/main/bbpack/*.cmd</TD></TR><TR><TD>/office:../bbpack/*.cmd</TD><TD></TD><TD>//depot/private/office/bbpack/*.cmd</TD></TR></TABLE>
<H2><A NAME=psych>sdv special powers</A></H2>
<P>sdv was bitten by a radioactive spider and has as a consequencebeen imbued with <I>special powers</I> that sometimes come in handy.
<H3>Net use'd to another enlistment</H3>
sdv detects that the currentdirectly belongs to somebody else's enlistment and fiddles theparameters that it sends to sd so the "right" thing happens.Normally, sd bails with an error message like<PRE>Path 'Z:\' is not under client's root 'C:\src'.</PRE>
<H3>Gauntlet</H3>
<P>sdv has special knowledge of the<A HREF=http://toolbox/search/tbdetail.asp?ToolID=1086>Gauntlet</A> checkin process anddisplays Gauntlet checkins as if they had been checkedin by the submitting developer (rather than by the Gauntlet machine).
<H3>proxy checkins</H3>
<P>sdv recognizes the following patterns at the start of a checkindescription and treats them as proxy checkins.
<PRE>123456 (developer) comment123456 [developer] comment(developer) comment[developer] comment</PRE>
<H3>RAID bugs</H3>
<P>sdv sniffs around the checkin comment looking for things which mightbe bug numbers. When it finds one, it will offer to view the RAID bugas a web page. By default, the bug is interpreted as a bug in theWindows NT database. You can override this by setting the SDVRAIDenvironment variable. Its value is a command line to execute,with a "#" where the bug number should go. (Typically a program witharguments or an URL.)
<P>For example, you might use<PRE>set SDVRAID=http://www.imdb.com/Title?#</PRE>
to cause bugs to link to random movies from the Internet Movie Database.(Well, except that if your database has more bugs than the IMDb has movies,you'll end up with a bunch of broken links, but this was just a jokesuggestion anyway.)
<H2><A NAME=limit>Limitations</A></H2>
<UL><LI><P>The branch resolver will get confused if you try to apply it to somethingthat doesn't have a branch name. For example, if you type
<PRE>main://depot/.../i386/...</PRE>
then you deserve what you get.</P>
<LI><P>The branch resolver and the code that tries to figure out borrowedenlistments can get faked out by complicated client viewswhich move directories around or edit filenames.</P>
<LI><P>The code that tries to figure out borrowed enlistments will fail ifyour client root is set to the null string. If you are perverseenough to do this, then you deserve what you get.</P>
<LI><P>Only the first bug number found is auto-linked by the bug number sniffer.For the others, you will have to type the bug number into Raid manually.This will teach you not to batch fixes for multiple bugs into a singlechangelist.</P>
<LI><P>If multiple integrations to a file aresubmitted as a single change, only one of them will be displayedin the "filelog" list. Fortunately, very few people do this, but if youare one of those people, consider yourself warned.This is arguably a bug, but fixing it is tricky so I'm going to waitand see if anybody complains.</P>
</UL>
<H2>Appendix</H2>
<H3><A NAME=ntbrn>Windows NT branch model</A></H3>
<UL><LI><P>//depot/branchname/... are official, or "top-level" branches. The main branch is called "main". </P>
<LI><P>//depot/private/branchname/... are private branches.
</UL>
<P>The file hierarchies under each branch are identical. In otherwords, the branch specifications are always of the form<PRE> //depot/donor/aaaa/... //depot/recipient/aaaa/... //depot/donor/bbbb/cccc/... //depot/recipient/bbbb/cccc/...</PRE>where "donor" and "recipient" are either a top-level branch nameor a private branch name in the form "private/name".
<P>These rules make it relatively easy to track the relationshipsbetween files because you can determine whether two files areconnected via branch integrations just by looking at their full depotpaths:
<PRE>//depot/W/aaa/bbb/ccc/ddd//depot/X/aaa/bbb/ccc/ddd//depot/private/Y/aaa/bbb/ccc/ddd//depot/private/Z/aaa/bbb/ccc/ddd</PRE>
are all related to each other by chains of integrations.
</BODY></HTML>
|
