Upload Diffs

You can upload local file differences with the adddiffs command:

The path-from and 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:

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:

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:

After you upload diffs to the server you will see the "changelist" appear similar to this:

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 ccollab adddiffs.

Version Control specific add*diffs commands:

• addardiffs (AccuRev)
• addcvsdiffs (CVS)
• addgitdiffs (Git)
• addhgdiffs (Mercurial)
• addp4diffs (Perforce)
• addsvndiffs (Subversion)

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 ccollab add*diffs.

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.

• Unified
  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 ccollab command-line. This can be especially handy if you are writing a script to automate this process.

• Subversion Style
  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 addsvndiffs instead of adddiffs.

• Perforce Style
  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 addp4diffs instead of adddiffs.

• CVS Style
  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 addcvsdiffs instead of adddiffs.

• GNU Format
  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.

• RCS Format
  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.

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 diff the command-line option is -u1000 where 1000 is 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*diffs commands whenever you can. This automatically selects the right command-line switches to maximize context while minimizing data transmissions.