VssReporter requires Visual SourceSafe 5 or 6 to be pre-installed, both to run it and to build it.
Since this is not a free redistributable (as far as I am aware) I cannot include even the VSS component (ssapi.dll) that VssReporter requires.
Note: If anyone can point me to a Microsoft document that proves me wrong, then I will gladly include ssapi.dll - but not at the present.
With most real-world activities its fairly easy to determine whether someone has done something or not:
"Jimmy, have you cleaned your room?"
(clump, clump, clump - sound of dad walking upstairs)
"No you jolly well haven't (or words to that effect). Get to it"
Software, however, is a completely different kettle of fish.
The bit you see (the binary's UI, web page or other) is generally just the tip of the iceberg (especially with binaries), with most of what really makes up the component hidden away out of sight.
Moreover, compiled binaries are further complicated by the extra level of indirection caused by the compilation process; something that becomes all too painfully clear to the unlucky sod responsible for performing regular builds on projects of more than one person.
It sounds so simple, mailing all the coders to find out what they've worked on since the last build. But that's when you discover that few coders retain a clear memory of exactly what they fixed (or broke) in the preceding week (or even day).
Indeed, some can barely remember what they had for breakfast ;)
It's the things we do almost unconsciously, like minor refactoring (aka 'spring cleaning' or 'tidying up'), that are especially prone to being forgotten.
I have had many experiences caused by both myself and others where an apparently innocuous 'minor' code change has caused no end of trouble because no one can recall changing anything in the code where the problem occurs.
At its simplest, VssReporter is a tool for querying SourceSafe to find out what source files have been changed after, before or between certain date(s).
Dates can be an explicit eg '02/08/2002' or the implicit eg a label.
It will allow you to query for modifications made by anyone, only yourself, or a named coder.
However, as handy as that may (or may not) sound, I've found that VssReporter's most significant value has been in the variety of problems to which I've been able to apply it.
Here are a few:
As I mentioned before, being responsible for builds means you have to know exactly what has changed since the last build. Otherwise you can't possibly write appropriate release notes which means that the product you're building becomes increasingly undefined as time goes by.
Having been responsible for builds on a number of projects on which I also coded, I found VssReporter indispensible.
This is how I worked it:
- First I decided on a label to be used after every build eg 'Last Build'. Note: reusing the same label in VSS simply moves the label to the latest use rather than duplicating it.
- Then, prior to every build I would run the same query in VssReporter to determine what files had changed since the label was last used.
- Then I would go hassle a coder about any file changes they had done which did not correspond to any of things we were meant to be changing for the build.
- Finally I would re-label the project when I'd done the build.
I even caught myself out a few times when I discovered that I made some 'trivial' changes that I barely remembered making!
Just recently I was required to make a number of small changes to a set of components ostensibly contained within a single Vss project root.
All personnel who had previously worked on these components had left the company and so I was delegated the task.
What I found when I tried to build the components was a real dog's breakfast:
- Multiple copies of sourcefiles and projects existed within different workspaces
- Projects had been moved meaning they no longer could be built
- Each project had a mass of test projects that different coders had concocted at different times
"There's only one thing to do", I said to a co-worker, "re-structure the whole bloody thing!". To which he replied, "Well overdue".
That's when i hit a snag: how to determine what code really needed to be rebuilt since, in case you think this was a trivial exercise, I counted 47 projects stored below the root folder, all for 7 principal components.
First I spent an hour trying to figure it out the hard way, getting progressively more demoralized, until i couldn't stand it any more and went to whinge to Ed (my closest co-worker).
As i regaled him with the litany of short-sighted changes that had been made over the years, it occurred to me that all i needed was a way of determining what code had changed, say, over the last year as an indicator of what code was currently in use.
Two queries with VssReporter and a couple of hours later and the whole thing was done!
To my continued dismay as a programmer, I never cease to be amazed at how many of my co-workers will modify someone else's code simply because they can.
This is less my direct experience (I find people never modify my code more than once if you get my meaning), than observing a team of 4 guys working on a 3D engine a few years ago.
Every so often you would hear a scream because a fix someone had implemented had been 'unfixed' a few days later.
Similar problems occur with shared code libaries: a fix for one project can break another.
So every so often I now run VssReporter queries on certain projects to see if anything has changed - 'forewarned is forarmed' (or however it goes).
- Copy VssReporter.exe to a suitable tools location.
- Run it.
- You may be prompted to locate ssapi.dll if its not registered but this is unlikely if VSS is installed correctly.
Using VssReporter is almost as trivial as installing it:
- Select (or Browse) to your VSS database of choice.
Note: this will be saved on closing VssReporter and restored on next run.
- Highlight the VSS project on which you want to run your query.
- Select whether you are interested in file changes made by everyone, just yourself or a specific programmer.
- Choose whether to query 'After', 'Before' or 'Between' dates or labels
- Enter the date(s) or label(s)
- Click the 'Report' button.
This will generate a list of files in the right-hand list control which, if you scroll the list to the right, also displays the last time the file was changed and the person who changed it.
Thereafter you can either copy the results to the clipboard as formatted text, or right-click on individual files and open SourceSafe on the parent project.
VssReporter manipulates VSS via the object model exported by the type library contained within ssapi.dll (does that sound right?).
Essentially its just a case of calling
#import "ssapi.dll" no_namespace
in whatever files you want to access VSS's object model.
Then its a case of reading whatever documentation you can lay your mits on and carrying out lots of trial and error.
I think the core of the VSS code on VssReporter came from MSDN but if anyone thinks that there is credit due to anyone whose code I might have used then please tell me and I'll add a credit.
Other points of interest
Because the VSS related bits of VssReporter are not that exciting, I thought I'd point out some other bits and pieces that you might find useful.
- Filling a tree control on demand (see
CVSSTreeCtrl::OnItemexpanding() in VSSTreeCtrl.cpp)
- Implementing a 'Stop' button to cancel a lengthy operation (see
CVssreporterDlg::Continue() in VSSReporterDlg.cpp)
- Executing an application and waiting until it has terminated before continuing (see
CVssreporterDlg::OnInitDialog() in VSSReporterDlg.cpp)
- Simple clipboard usage (see
CVssreporterDlg::OnCopytoclipboard() in VSSReporterDlg.cpp)
- Facility to additionally check for files currently checked out.
The code is supplied here for you to use and abuse without restriction, except that you may not modify it and pass it off as your own.
- 2.1 (26 Mar 2006)
- system 'Asterisk' sound played at the end of a search
- manifest added (to give themed support)
- tabbed file delimiter bug fixed
- file label added to results list
- label search changed to 'containing' rather than 'equals' to give more flexibility
- username/password to commandline when invoking VSS
- file type icon moved into separate result column to enable sorting on type
- dialog fonts changed to tahoma
- prompt added to not rebuild tree when copying files (ie folder structure is flattened)
- 2.0 (10 Sep 2004)
- support added for Visual SourceSafe 5
- support added for deleted files
- icons added to results list to differentiate between additions, edits and deletions
- 1.9.2 (10 Mar 2004)
- fixed bugs relating to incorrect cleanup of smart pointers
- 1.9.1 (3 Mar 2004)
- 1.9 (12 Feb 2004)
- fixed a bug relating to searching on labels where labels attached to check-ins were not being searched
- added 'diffing' capabilities to the results list. specify the diff tool of your own choice via the 'Diff Config...' button
- comments added to the results list
- minor clarification tweaks to the query description text
- fixes bug relating to entering 'other coders' names containing spaces (thanks to Miles Davies)
- 'other coders' names containg spaces are now enclosed in single quotes
- adds options to save results as xml (suggested by Rob Hegt)
- attempts to clarify what to expect from queries (suggested by Judd)
- fixes some more query related UI bugs (thanks to Judd)
- adds "Select all" and "copy" options to results context menu (suggested by KLIKLI)
- now only the selected results are copied/saved
- adds option to tab-delimit results text for easy import into excel (suggested by KLIKLI)
- fixes bug where date/time was not getting copied with the other results text (thanks to KLIKLI)
- recursive checkbox added to give more control over the depth of the search (suggested by KLIKLI)
- results filename and path now in separate columns (suggested by KLIKLI)
- results header control now shows sort direction
- various query dialog related UI tweaks (thanks to Judd)
- fixes bug on label queries where the details of the lael were being displayed rather than the details for the last mod immediately preceding the label (thanks to KLIKLI).
- fixes bug where duplicate entries were shown for 'last modified' queries (thanks to KLIKLI)
- password edit box has the focus on startup (suggested by KLIKLI)
- version number added to dialog titlebar (suggested by KLIKLI)
- substantial refactoring
- more efficient => faster reporting
- plain english summary of current query
- added results column sorting (suggested by KLIKLI)
- added facility to report on files having a certain label (suggested by Uli Grepel)
- added facility to report on all versions of files between/before or after a certain label or date (suggested by KLIKLI)
- added some more try/catch code around key ssapi.dll calls.
- fixed localization problems (thanks to tbrammer)
- added facility for saving results directly to file (thanks to ???)
- added facility for copying result files to user defined folder (thanks to Henrik Grek )
- fixed bug in filtering code where some items would not be correctly reported (thanks to tbrammer)
- add handling for return key so that when the username/password fields have the focus it will reload the selected database (thanks to KLIKLI)
- version number added to exe resources (thanks to KLIKLI)
- minor bug fixes
- significantly speeded up the 'results->text' generation when copying results to clipboard or file
- added some try/catch code around key ssapi.dll calls. These can throw exceptions if, for instance, the user does not have the correct permissions to view a file (thanks to Robert Harber)
- improved user feedback if one of other of the labels cannot be found.
- minor reworking so that 'label finding' can also be stopped using the 'Stop' button
- possible fix for Vision Guy relating to reporting on dates and labels (no promises!)
- support added to allow modification of the vss login name and password (thanks to shtwang, Judd, Marco)
- spurious reference to vsdiff.h removed from vssreporterdlg.h (thanks to Dfens)