You can upload arbitrary file differences using the
ccollab adddiffs command. This subject is complex enough to warrant its own section in the manual.
Uploading Local File Diffs
You can upload local file differences with the
ccollab adddiffs <review> path-from path-to
path-to fields are paths to two files or directories to compare, and <review> is an integer review-id, 'new', 'ask', or 'last'. For example, this command would upload any differences found as a change-set as a new review:
ccollab adddiffs new /old/directory /new/directory
Uploading Arbitrary Diffs
You can also upload arbitrary differences with the
adddiffs command. Assuming textual diffs have already been generated in a file called diffs.txt, use this:
ccollab adddiffs review diffs.txt
Or you can pipe the results of another diff command right into the
ccollab process using a single dash instead of a file path. For example, this command uses the GNU
diff command to generate a unified diff format, then uploads it directly into review #2534:
diff -u100 dir1 dir2 | ccollab adddiffs 2534 -
After you upload diffs to the server you will see the "changelist" appear similar to this:
Uploading Differences from Version Control
If you want to upload differences generated by a version control command-line tool, you should use the
ccollab add*diffs command specific to your version control system (if available) instead of
Version Control specific
These commands integrate with version control servers and supply exactly the right command-line switches to the underlying version control command-line to minimize server transmissions and maximize features like fully reproducing both previous and current versions of the document.
Many of the pitfalls with diffs described below are avoided when using
Supported Diff Formats
There are many kinds of diff formats out there. Our software supports many of them; if you find a format that is not working, please let us know so we can get your diff format into our unit tests.
The unified format starts with a two-line header naming the previous and name versions of a file, plus optional file information. Then it follows with diff-chunks starting with "@@" and then having both unmodified lines and added/removed lines. An exact definition of the format can be found here.
Any number of these file-diffs can be strung together. Our software parses all of the files and uploads each as a "before" and "after" version. Context lines are preserved; lines skipped are reconstructed (more about this later).
UltraCompare Text Format
We support the proprietary text format emitted by the 3rd party commercial command-line tool UltraCompare.
This is a Unicode diff with full file context making it an excellent format that preserves all file content.
Although this utility emits only one file difference at a time, you can concatenate any number of these diffs together and upload them in one shot through the
ccollabcommand-line. This can be especially handy if you are writing a script to automate this process.
Subversion outputs a two-line header for each file; one starts with "Index:" and names the file in question, the next is a row of equal signs. Following the header is any of three types of diff output; we support all three but you should use the unified format for best results. Any number of these file-diffs can be strung together.
Note that with Subversion you should use
Perforce has a variety of output formats; we support all of them. One is just the Unified format specified above. The other uses a one-line file header that shows the "before" and "after" file paths and version numbers with other file data, and then uses any of three types of diff output to encode the diffs. We support all three but you should use the unified format for best results. Any number of these file-diffs can be strung together.
Note that with Perforce you should use
Similar to Subversion Style (see above) but has additional lines of output besides just those two file header markers.
Note that with CVS you should use
The GNU format shows just additions, deletions, and modifications with no file context. An exact definition of the format can be found here.
We do not recommend you use GNU format because (1) it does not support file names or multiple files and (2) it does not support context lines which causes problems when reconstructing files.
The RCS format shows just additions and deletions with no file context.
We do not recommend you use RCS format because (1) it does not support file names or multiple files and (2) it does not support context lines which causes problems when reconstructing files.
Araxis Merge, BeyondCompare, GuiffyMerge, GNU diff, xdiff, and other tools
With these diff utilities, use an export option that creates unified diffs with lots of context. See the guidelines below.
When the command-line utility is uploading diffs it will print out the format that was detected. If it complains that the format is unknown, attach a copy of your diff data to an email to our tech support department so we can add support for your format.
Context Lines and Reconstructing Files
Most diff formats skip over lines that were unchanged, possibly leaving a few lines of "context" around each modification. This might be OK for "patch" utilities but it is not good when you want to do a review. Why not?
When you do the review, if you do not have many lines of context you cannot see much beyond the diffs themselves. Our software is smart enough to reconstruct the two files as well as possible, retaining all line numbers, but of course there will be gaps.
Here is how the side-by-side view looks with some differences that only had three lines of context:
You can see the "
*** unspecified line placeholder ***" text where the diff skipped over lines.
How to prevent this? It depends on how you are generating diffs. Here are some guidelines:
Always use Unified diff format, not RCS or GNU. Those others do not support lines of context at all, nor do they support filenames so your uploads will be "anonymous".
Always include a lot of context with your Unified diff format. The way to specify this varies depending on your diff utility. For example, using GNU
diffthe command-line option is
1000is the number of lines of context. Selecting a big number like 1000 is not unreasonable! Reviewers will thank you for it.
Use the version-control specific
ccollab add*diffscommands whenever you can. This automatically selects the right command-line switches to maximize context while minimizing data transmissions.