Show More
@@ -415,3 +415,359 b' announcements. Clients assume servers wi' | |||
|
415 | 415 | Mercurial server replies to the client-issued commands. So any server output |
|
416 | 416 | not conforming to the expected command responses is assumed to be not related |
|
417 | 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