cvsserver Documentation: new cvs ... -r support
Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Matthew Ogilvie committed
Oct 13, 2012 at 23:42 UTC
96bc8f66f9f3a56c89c9440171049c95f162a3fa
1 file changed
+37
Documentation/git-cvsserver.txt
+37
@@ -359,6 +359,43 @@ Operations supported
359
360
All the operations required for normal use are supported, including
361
checkout, diff, status, update, log, add, remove, commit.
362
+
363
+Most CVS command arguments that read CVS tags or revision numbers
364
+(typically -r) work, and also support any git refspec
365
+(tag, branch, commit ID, etc).
366
+However, CVS revision numbers for non-default branches are not well
367
+emulated, and cvs log does not show tags or branches at
368
+all. (Non-main-branch CVS revision numbers superficially resemble CVS
369
+revision numbers, but they actually encode a git commit ID directly,
370
+rather than represent the number of revisions since the branch point.)
371
+
372
+Note that there are two ways to checkout a particular branch.
373
+As described elsewhere on this page, the "module" parameter
374
+of cvs checkout is interpreted as a branch name, and it becomes
375
+the main branch. It remains the main branch for a given sandbox
376
+even if you temporarily make another branch sticky with
377
+cvs update -r. Alternatively, the -r argument can indicate
378
+some other branch to actually checkout, even though the module
379
+is still the "main" branch. Tradeoffs (as currently
380
+implemented): Each new "module" creates a new database on disk with
381
+a history for the given module, and after the database is created,
382
+operations against that main branch are fast. Or alternatively,
383
+-r doesn't take any extra disk space, but may be significantly slower for
384
+many operations, like cvs update.
385
+
386
+If you want to refer to a git refspec that has characters that are
387
+not allowed by CVS, you have two options. First, it may just work
388
+to supply the git refspec directly to the appropriate CVS -r argument;
389
+some CVS clients don't seem to do much sanity checking of the argument.
390
+Second, if that fails, you can use a special character escape mechanism
391
+that only uses characters that are valid in CVS tags. A sequence
392
+of 4 or 5 characters of the form (underscore (`"_"`), dash (`"-"`),
393
+one or two characters, and dash (`"-"`)) can encode various characters based
394
+on the one or two letters: `"s"` for slash (`"/"`), `"p"` for
395
+period (`"."`), `"u"` for underscore (`"_"`), or two hexadecimal digits
396
+for any byte value at all (typically an ASCII number, or perhaps a part
397
+of a UTF-8 encoded character).
398
+
399
Legacy monitoring operations are not supported (edit, watch and related).
400
Exports and tagging (tags and branches) are not supported at this stage.
401