Show More
@@ -415,3 +415,359 b' announcements. Clients assume servers wi' | |||||
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. |
General Comments 0
You need to be logged in to leave comments.
Login now