Mercurial > hg
comparison mercurial/help/internals/wireprotocol.txt @ 29865:80c11c1a64bf
help: document wire protocol commands
author | Gregory Szorc <gregory.szorc@gmail.com> |
---|---|
date | Mon, 22 Aug 2016 19:50:21 -0700 |
parents | f0d47aca1d47 |
children | 753b9d43ca81 |
comparison
equal
deleted
inserted
replaced
29864:f0d47aca1d47 | 29865:80c11c1a64bf |
---|---|
413 servers may also send other output, such as *message of the day (MOTD)* | 413 servers may also send other output, such as *message of the day (MOTD)* |
414 announcements. Clients assume servers will send this output before the | 414 announcements. Clients assume servers will send this output before the |
415 Mercurial server replies to the client-issued commands. So any server output | 415 Mercurial server replies to the client-issued commands. So any server output |
416 not conforming to the expected command responses is assumed to be not related | 416 not conforming to the expected command responses is assumed to be not related |
417 to Mercurial and can be ignored. | 417 to Mercurial and can be ignored. |
418 | |
419 Commands | |
420 ======== | |
421 | |
422 This section contains a list of all wire protocol commands implemented by | |
423 the canonical Mercurial server. | |
424 | |
425 batch | |
426 ----- | |
427 | |
428 Issue multiple commands while sending a single command request. The purpose | |
429 of this command is to allow a client to issue multiple commands while avoiding | |
430 multiple round trips to the server therefore enabling commands to complete | |
431 quicker. | |
432 | |
433 The command accepts a ``cmds`` argument that contains a list of commands to | |
434 execute. | |
435 | |
436 The value of ``cmds`` is a ``;`` delimited list of strings. Each string has the | |
437 form ``<command> <arguments>``. That is, the command name followed by a space | |
438 followed by an argument string. | |
439 | |
440 The argument string is a ``,`` delimited list of ``<key>=<value>`` values | |
441 corresponding to command arguments. Both the argument name and value are | |
442 escaped using a special substitution map:: | |
443 | |
444 : -> :c | |
445 , -> :o | |
446 ; -> :s | |
447 = -> :e | |
448 | |
449 The response type for this command is ``string``. The value contains a | |
450 ``;`` delimited list of responses for each requested command. Each value | |
451 in this list is escaped using the same substitution map used for arguments. | |
452 | |
453 If an error occurs, the generic error response may be sent. | |
454 | |
455 between | |
456 ------- | |
457 | |
458 (Legacy command used for discovery in old clients) | |
459 | |
460 Obtain nodes between pairs of nodes. | |
461 | |
462 The ``pairs`` arguments contains a space-delimited list of ``-`` delimited | |
463 hex node pairs. e.g.:: | |
464 | |
465 a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896-6dc58916e7c070f678682bfe404d2e2d68291a18 | |
466 | |
467 Return type is a ``string``. Value consists of lines corresponding to each | |
468 requested range. Each line contains a space-delimited list of hex nodes. | |
469 A newline ``\n`` terminates each line, including the last one. | |
470 | |
471 branchmap | |
472 --------- | |
473 | |
474 Obtain heads in named branches. | |
475 | |
476 Accepts no arguments. Return type is a ``string``. | |
477 | |
478 Return value contains lines with URL encoded branch names followed by a space | |
479 followed by a space-delimited list of hex nodes of heads on that branch. | |
480 e.g.:: | |
481 | |
482 default a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896 6dc58916e7c070f678682bfe404d2e2d68291a18 | |
483 stable baae3bf31522f41dd5e6d7377d0edd8d1cf3fccc | |
484 | |
485 There is no trailing newline. | |
486 | |
487 branches | |
488 -------- | |
489 | |
490 Obtain ancestor changesets of specific nodes back to a branch point. | |
491 | |
492 Despite the name, this command has nothing to do with Mercurial named branches. | |
493 Instead, it is related to DAG branches. | |
494 | |
495 The command accepts a ``nodes`` argument, which is a string of space-delimited | |
496 hex nodes. | |
497 | |
498 For each node requested, the server will find the first ancestor node that is | |
499 a DAG root or is a merge. | |
500 | |
501 Return type is a ``string``. Return value contains lines with result data for | |
502 each requested node. Each line contains space-delimited nodes followed by a | |
503 newline (``\n``). The 4 nodes reported on each line correspond to the requested | |
504 node, the ancestor node found, and its 2 parent nodes (which may be the null | |
505 node). | |
506 | |
507 capabilities | |
508 ------------ | |
509 | |
510 Obtain the capabilities string for the repo. | |
511 | |
512 Unlike the ``hello`` command, the capabilities string is not prefixed. | |
513 There is no trailing newline. | |
514 | |
515 This command does not accept any arguments. Return type is a ``string``. | |
516 | |
517 changegroup | |
518 ----------- | |
519 | |
520 (Legacy command: use ``getbundle`` instead) | |
521 | |
522 Obtain a changegroup version 1 with data for changesets that are | |
523 descendants of client-specified changesets. | |
524 | |
525 The ``roots`` arguments contains a list of space-delimited hex nodes. | |
526 | |
527 The server responds with a changegroup version 1 containing all | |
528 changesets between the requested root/base nodes and the repo's head nodes | |
529 at the time of the request. | |
530 | |
531 The return type is a ``stream``. | |
532 | |
533 changegroupsubset | |
534 ----------------- | |
535 | |
536 (Legacy command: use ``getbundle`` instead) | |
537 | |
538 Obtain a changegroup version 1 with data for changesetsets between | |
539 client specified base and head nodes. | |
540 | |
541 The ``bases`` argument contains a list of space-delimited hex nodes. | |
542 The ``heads`` argument contains a list of space-delimited hex nodes. | |
543 | |
544 The server responds with a changegroup version 1 containing all | |
545 changesets between the requested base and head nodes at the time of the | |
546 request. | |
547 | |
548 The return type is a ``stream``. | |
549 | |
550 clonebundles | |
551 ------------ | |
552 | |
553 Obtains a manifest of bundle URLs available to seed clones. | |
554 | |
555 Each returned line contains a URL followed by metadata. See the | |
556 documentation in the ``clonebundles`` extension for more. | |
557 | |
558 The return type is a ``string``. | |
559 | |
560 getbundle | |
561 --------- | |
562 | |
563 Obtain a bundle containing repository data. | |
564 | |
565 This command accepts the following arguments: | |
566 | |
567 heads | |
568 List of space-delimited hex nodes of heads to retrieve. | |
569 common | |
570 List of space-delimited hex nodes that the client has in common with the | |
571 server. | |
572 obsmarkers | |
573 Boolean indicating whether to include obsolescence markers as part | |
574 of the response. Only works with bundle2. | |
575 bundlecaps | |
576 Comma-delimited set of strings defining client bundle capabilities. | |
577 listkeys | |
578 Comma-delimited list of strings of ``pushkey`` namespaces. For each | |
579 namespace listed, a bundle2 part will be included with the content of | |
580 that namespace. | |
581 cg | |
582 Boolean indicating whether changegroup data is requested. | |
583 cbattempted | |
584 Boolean indicating whether the client attempted to use the *clone bundles* | |
585 feature before performing this request. | |
586 | |
587 The return type on success is a ``stream`` where the value is bundle. | |
588 On the HTTP transport, the response is zlib compressed. | |
589 | |
590 If an error occurs, a generic error response can be sent. | |
591 | |
592 Unless the client sends a false value for the ``cg`` argument, the returned | |
593 bundle contains a changegroup with the nodes between the specified ``common`` | |
594 and ``heads`` nodes. Depending on the command arguments, the type and content | |
595 of the returned bundle can vary significantly. | |
596 | |
597 The default behavior is for the server to send a raw changegroup version | |
598 ``01`` response. | |
599 | |
600 If the ``bundlecaps`` provided by the client contain a value beginning | |
601 with ``HG2``, a bundle2 will be returned. The bundle2 data may contain | |
602 additional repository data, such as ``pushkey`` namespace values. | |
603 | |
604 heads | |
605 ----- | |
606 | |
607 Returns a list of space-delimited hex nodes of repository heads followed | |
608 by a newline. e.g. | |
609 ``a9eeb3adc7ddb5006c088e9eda61791c777cbf7c 31f91a3da534dc849f0d6bfc00a395a97cf218a1\n`` | |
610 | |
611 This command does not accept any arguments. The return type is a ``string``. | |
612 | |
613 hello | |
614 ----- | |
615 | |
616 Returns lines describing interesting things about the server in an RFC-822 | |
617 like format. | |
618 | |
619 Currently, the only line defines the server capabilities. It has the form:: | |
620 | |
621 capabilities: <value> | |
622 | |
623 See above for more about the capabilities string. | |
624 | |
625 SSH clients typically issue this command as soon as a connection is | |
626 established. | |
627 | |
628 This command does not accept any arguments. The return type is a ``string``. | |
629 | |
630 listkeys | |
631 -------- | |
632 | |
633 List values in a specified ``pushkey`` namespace. | |
634 | |
635 The ``namespace`` argument defines the pushkey namespace to operate on. | |
636 | |
637 The return type is a ``string``. The value is an encoded dictionary of keys. | |
638 | |
639 Key-value pairs are delimited by newlines (``\n``). Within each line, keys and | |
640 values are separated by a tab (``\t``). Keys and values are both strings. | |
641 | |
642 lookup | |
643 ------ | |
644 | |
645 Try to resolve a value to a known repository revision. | |
646 | |
647 The ``key`` argument is converted from bytes to an | |
648 ``encoding.localstr`` instance then passed into | |
649 ``localrepository.__getitem__`` in an attempt to resolve it. | |
650 | |
651 The return type is a ``string``. | |
652 | |
653 Upon successful resolution, returns ``1 <hex node>\n``. On failure, | |
654 returns ``0 <error string>\n``. e.g.:: | |
655 | |
656 1 273ce12ad8f155317b2c078ec75a4eba507f1fba\n | |
657 | |
658 0 unknown revision 'foo'\n | |
659 | |
660 known | |
661 ----- | |
662 | |
663 Determine whether multiple nodes are known. | |
664 | |
665 The ``nodes`` argument is a list of space-delimited hex nodes to check | |
666 for existence. | |
667 | |
668 The return type is ``string``. | |
669 | |
670 Returns a string consisting of ``0``s and ``1``s indicating whether nodes | |
671 are known. If the Nth node specified in the ``nodes`` argument is known, | |
672 a ``1`` will be returned at byte offset N. If the node isn't known, ``0`` | |
673 will be present at byte offset N. | |
674 | |
675 There is no trailing newline. | |
676 | |
677 pushkey | |
678 ------- | |
679 | |
680 Set a value using the ``pushkey`` protocol. | |
681 | |
682 Accepts arguments ``namespace``, ``key``, ``old``, and ``new``, which | |
683 correspond to the pushkey namespace to operate on, the key within that | |
684 namespace to change, the old value (which may be empty), and the new value. | |
685 All arguments are string types. | |
686 | |
687 The return type is a ``string``. The value depends on the transport protocol. | |
688 | |
689 The SSH transport sends a string encoded integer followed by a newline | |
690 (``\n``) which indicates operation result. The server may send additional | |
691 output on the ``stderr`` stream that should be displayed to the user. | |
692 | |
693 The HTTP transport sends a string encoded integer followed by a newline | |
694 followed by additional server output that should be displayed to the user. | |
695 This may include output from hooks, etc. | |
696 | |
697 The integer result varies by namespace. ``0`` means an error has occurred | |
698 and there should be additional output to display to the user. | |
699 | |
700 stream_out | |
701 ---------- | |
702 | |
703 Obtain *streaming clone* data. | |
704 | |
705 The return type is either a ``string`` or a ``stream``, depending on | |
706 whether the request was fulfilled properly. | |
707 | |
708 A return value of ``1\n`` indicates the server is not configured to serve | |
709 this data. If this is seen by the client, they may not have verified the | |
710 ``stream`` capability is set before making the request. | |
711 | |
712 A return value of ``2\n`` indicates the server was unable to lock the | |
713 repository to generate data. | |
714 | |
715 All other responses are a ``stream`` of bytes. The first line of this data | |
716 contains 2 space-delimited integers corresponding to the path count and | |
717 payload size, respectively:: | |
718 | |
719 <path count> <payload size>\n | |
720 | |
721 The ``<payload size>`` is the total size of path data: it does not include | |
722 the size of the per-path header lines. | |
723 | |
724 Following that header are ``<path count>`` entries. Each entry consists of a | |
725 line with metadata followed by raw revlog data. The line consists of:: | |
726 | |
727 <store path>\0<size>\n | |
728 | |
729 The ``<store path>`` is the encoded store path of the data that follows. | |
730 ``<size>`` is the amount of data for this store path/revlog that follows the | |
731 newline. | |
732 | |
733 There is no trailer to indicate end of data. Instead, the client should stop | |
734 reading after ``<path count>`` entries are consumed. | |
735 | |
736 unbundle | |
737 -------- | |
738 | |
739 Send a bundle containing data (usually changegroup data) to the server. | |
740 | |
741 Accepts the argument ``heads``, which is a space-delimited list of hex nodes | |
742 corresponding to server repository heads observed by the client. This is used | |
743 to detect race conditions and abort push operations before a server performs | |
744 too much work or a client transfers too much data. | |
745 | |
746 The request payload consists of a bundle to be applied to the repository, | |
747 similarly to as if :hg:`unbundle` were called. | |
748 | |
749 In most scenarios, a special ``push response`` type is returned. This type | |
750 contains an integer describing the change in heads as a result of the | |
751 operation. A value of ``0`` indicates nothing changed. ``1`` means the number | |
752 of heads remained the same. Values ``2`` and larger indicate the number of | |
753 added heads minus 1. e.g. ``3`` means 2 heads were added. Negative values | |
754 indicate the number of fewer heads, also off by 1. e.g. ``-2`` means there | |
755 is 1 fewer head. | |
756 | |
757 The encoding of the ``push response`` type varies by transport. | |
758 | |
759 For the SSH transport, this type is composed of 2 ``string`` responses: an | |
760 empty response (``0\n``) followed by the integer result value. e.g. | |
761 ``1\n2``. So the full response might be ``0\n1\n2``. | |
762 | |
763 For the HTTP transport, the response is a ``string`` type composed of an | |
764 integer result value followed by a newline (``\n``) followed by string | |
765 content holding server output that should be displayed on the client (output | |
766 hooks, etc). | |
767 | |
768 In some cases, the server may respond with a ``bundle2`` bundle. In this | |
769 case, the response type is ``stream``. For the HTTP transport, the response | |
770 is zlib compressed. | |
771 | |
772 The server may also respond with a generic error type, which contains a string | |
773 indicating the failure. |