docs/api/methods/repo-methods.rst

.. _repo-methods-ref:

repo methods
=================

add_field_to_repo 
-----------------

.. py:function:: add_field_to_repo(apiuser, repoid, key, label=<Optional:''>, description=<Optional:''>)

   Adds an extra field to a repository.

   This command can only be run using an |authtoken| with at least
   write permissions to the |repo|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: Set the repository name or repository id.
   :type repoid: str or int
   :param key: Create a unique field key for this repository.
   :type key: str
   :param label:
   :type label: Optional(str)
   :param description:
   :type description: Optional(str)


comment_commit 
--------------

.. py:function:: comment_commit(apiuser, repoid, commit_id, message, userid=<Optional:<OptionalAttr:apiuser>>, status=<Optional:None>)

   Set a commit comment, and optionally change the status of the commit.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: Set the repository name or repository ID.
   :type repoid: str or int
   :param commit_id: Specify the commit_id for which to set a comment.
   :type commit_id: str
   :param message: The comment text.
   :type message: str
   :param userid: Set the user name of the comment creator.
   :type userid: Optional(str or int)
   :param status: status, one of 'not_reviewed', 'approved', 'rejected',
      'under_review'
   :type status: str

   Example error output:

   .. code-block:: json

       {
           "id" : <id_given_in_input>,
           "result" : {
               "msg": "Commented on commit `<commit_id>` for repository `<repoid>`",
               "status_change": null or <status>,
               "success": true
           },
           "error" :  null
       }


create_repo 
-----------

.. py:function:: create_repo(apiuser, repo_name, repo_type, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, copy_permissions=<Optional:False>)

   Creates a repository.

   * If the repository name contains "/", all the required repository
     groups will be created.

     For example "foo/bar/baz" will create |repo| groups "foo" and "bar"
     (with "foo" as parent). It will also create the "baz" repository
     with "bar" as |repo| group.

   This command can only be run using an |authtoken| with at least
   write permissions to the |repo|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repo_name: Set the repository name.
   :type repo_name: str
   :param repo_type: Set the repository type; 'hg','git', or 'svn'.
   :type repo_type: str
   :param owner: user_id or username
   :type owner: Optional(str)
   :param description: Set the repository description.
   :type description: Optional(str)
   :param private:
   :type private: bool
   :param clone_uri:
   :type clone_uri: str
   :param landing_rev: <rev_type>:<rev>
   :type landing_rev: str
   :param enable_locking:
   :type enable_locking: bool
   :param enable_downloads:
   :type enable_downloads: bool
   :param enable_statistics:
   :type enable_statistics: bool
   :param copy_permissions: Copy permission from group in which the
       repository is being created.
   :type copy_permissions: bool


   Example output:

   .. code-block:: bash

       id : <id_given_in_input>
       result: {
                 "msg": "Created new repository `<reponame>`",
                 "success": true,
                 "task": "<celery task id or None if done sync>"
               }
       error:  null


   Example error output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : null
     error :  {
        'failed to create repository `<repo_name>`
     }


delete_repo 
-----------

.. py:function:: delete_repo(apiuser, repoid, forks=<Optional:''>)

   Deletes a repository.

   * When the `forks` parameter is set it's possible to detach or delete
     forks of deleted repository.

   This command can only be run using an |authtoken| with admin
   permissions on the |repo|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: Set the repository name or repository ID.
   :type repoid: str or int
   :param forks: Set to `detach` or `delete` forks from the |repo|.
   :type forks: Optional(str)

   Example error output:

   .. code-block:: bash

       id : <id_given_in_input>
       result: {
                 "msg": "Deleted repository `<reponame>`",
                 "success": true
               }
       error:  null


fork_repo 
---------

.. py:function:: fork_repo(apiuser, repoid, fork_name, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, copy_permissions=<Optional:False>, private=<Optional:False>, landing_rev=<Optional:'rev:tip'>)

   Creates a fork of the specified |repo|.

   * If using |RCE| with Celery this will immediately return a success
     message, even though the fork will be created asynchronously.

   This command can only be run using an |authtoken| with fork
   permissions on the |repo|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: Set repository name or repository ID.
   :type repoid: str or int
   :param fork_name: Set the fork name.
   :type fork_name: str
   :param owner: Set the fork owner.
   :type owner: str
   :param description: Set the fork descripton.
   :type description: str
   :param copy_permissions: Copy permissions from parent |repo|. The
       default is False.
   :type copy_permissions: bool
   :param private: Make the fork private. The default is False.
   :type private: bool
   :param landing_rev: Set the landing revision. The default is tip.

   Example output:

   .. code-block:: bash

       id : <id_for_response>
       api_key : "<api_key>"
       args:     {
                   "repoid" :          "<reponame or repo_id>",
                   "fork_name":        "<forkname>",
                   "owner":            "<username or user_id = Optional(=apiuser)>",
                   "description":      "<description>",
                   "copy_permissions": "<bool>",
                   "private":          "<bool>",
                   "landing_rev":      "<landing_rev>"
                 }

   Example error output:

   .. code-block:: bash

       id : <id_given_in_input>
       result: {
                 "msg": "Created fork of `<reponame>` as `<forkname>`",
                 "success": true,
                 "task": "<celery task id or None if done sync>"
               }
       error:  null


get_repo 
--------

.. py:function:: get_repo(apiuser, repoid, cache=<Optional:True>)

   Gets an existing repository by its name or repository_id.

   The members section so the output returns users groups or users
   associated with that repository.

   This command can only be run using an |authtoken| with admin rights,
   or users with at least read rights to the |repo|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: The repository name or repository id.
   :type repoid: str or int
   :param cache: use the cached value for last changeset
   :type: cache: Optional(bool)

   Example output:

   .. code-block:: bash

       {
         "error": null,
         "id": <repo_id>,
         "result": {
           "clone_uri": null,
           "created_on": "timestamp",
           "description": "repo description",
           "enable_downloads": false,
           "enable_locking": false,
           "enable_statistics": false,
           "followers": [
             {
               "active": true,
               "admin": false,
               "api_key": "****************************************",
               "api_keys": [
                 "****************************************"
               ],
               "email": "[e-mail]",
               "emails": [
                 "[e-mail]"
               ],
               "extern_name": "rhodecode",
               "extern_type": "rhodecode",
               "firstname": "username",
               "ip_addresses": [],
               "language": null,
               "last_login": "2015-09-16T17:16:35.854",
               "lastname": "surname",
               "user_id": <user_id>,
               "username": "name"
             }
           ],
           "fork_of": "parent-repo",
           "landing_rev": [
             "rev",
             "tip"
           ],
           "last_changeset": {
             "author": "User <[e-mail]>",
             "branch": "default",
             "date": "timestamp",
             "message": "last commit message",
             "parents": [
               {
                 "raw_id": "commit-id"
               }
             ],
             "raw_id": "commit-id",
             "revision": <revision number>,
             "short_id": "short id"
           },
           "lock_reason": null,
           "locked_by": null,
           "locked_date": null,
           "members": [
             {
               "name": "super-admin-name",
               "origin": "super-admin",
               "permission": "repository.admin",
               "type": "user"
             },
             {
               "name": "owner-name",
               "origin": "owner",
               "permission": "repository.admin",
               "type": "user"
             },
             {
               "name": "user-group-name",
               "origin": "permission",
               "permission": "repository.write",
               "type": "user_group"
             }
           ],
           "owner": "owner-name",
           "permissions": [
             {
               "name": "super-admin-name",
               "origin": "super-admin",
               "permission": "repository.admin",
               "type": "user"
             },
             {
               "name": "owner-name",
               "origin": "owner",
               "permission": "repository.admin",
               "type": "user"
             },
             {
               "name": "user-group-name",
               "origin": "permission",
               "permission": "repository.write",
               "type": "user_group"
             }
           ],
           "private": true,
           "repo_id": 676,
           "repo_name": "user-group/repo-name",
           "repo_type": "hg"
         }
       }


get_repo_changeset 
------------------

.. py:function:: get_repo_changeset(apiuser, repoid, revision, details=<Optional:'basic'>)

   Returns information about a changeset.

   Additionally parameters define the amount of details returned by
   this function.

   This command can only be run using an |authtoken| with admin rights,
   or users with at least read rights to the |repo|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: The repository name or repository id
   :type repoid: str or int
   :param revision: revision for which listing should be done
   :type revision: str
   :param details: details can be 'basic|extended|full' full gives diff
       info details like the diff itself, and number of changed files etc.
   :type details: Optional(str)


get_repo_changesets 
-------------------

.. py:function:: get_repo_changesets(apiuser, repoid, start_rev, limit, details=<Optional:'basic'>)

   Returns a set of commits limited by the number starting
   from the `start_rev` option.

   Additional parameters define the amount of details returned by this
   function.

   This command can only be run using an |authtoken| with admin rights,
   or users with at least read rights to |repos|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: The repository name or repository ID.
   :type repoid: str or int
   :param start_rev: The starting revision from where to get changesets.
   :type start_rev: str
   :param limit: Limit the number of commits to this amount
   :type limit: str or int
   :param details: Set the level of detail returned. Valid option are:
       ``basic``, ``extended`` and ``full``.
   :type details: Optional(str)

   .. note::

      Setting the parameter `details` to the value ``full`` is extensive
      and returns details like the diff itself, and the number
      of changed files.


get_repo_nodes 
--------------

.. py:function:: get_repo_nodes(apiuser, repoid, revision, root_path, ret_type=<Optional:'all'>, details=<Optional:'basic'>, max_file_bytes=<Optional:None>)

   Returns a list of nodes and children in a flat list for a given
   path at given revision.

   It's possible to specify ret_type to show only `files` or `dirs`.

   This command can only be run using an |authtoken| with admin rights,
   or users with at least read rights to |repos|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: The repository name or repository ID.
   :type repoid: str or int
   :param revision: The revision for which listing should be done.
   :type revision: str
   :param root_path: The path from which to start displaying.
   :type root_path: str
   :param ret_type: Set the return type. Valid options are
       ``all`` (default), ``files`` and ``dirs``.
   :type ret_type: Optional(str)
   :param details: Returns extended information about nodes, such as
       md5, binary, and or content.  The valid options are ``basic`` and
       ``full``.
   :type details: Optional(str)
   :param max_file_bytes: Only return file content under this file size bytes
   :type details: Optional(int)

   Example output:

   .. code-block:: bash

       id : <id_given_in_input>
       result: [
                 {
                   "name" : "<name>"
                   "type" : "<type>",
                   "binary": "<true|false>" (only in extended mode)
                   "md5"  : "<md5 of file content>" (only in extended mode)
                 },
                 ...
               ]
       error:  null


get_repo_refs 
-------------

.. py:function:: get_repo_refs(apiuser, repoid)

   Returns a dictionary of current references. It returns
   bookmarks, branches, closed_branches, and tags for given repository

   It's possible to specify ret_type to show only `files` or `dirs`.

   This command can only be run using an |authtoken| with admin rights,
   or users with at least read rights to |repos|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: The repository name or repository ID.
   :type repoid: str or int

   Example output:

   .. code-block:: bash

       id : <id_given_in_input>
       result: [
                 TODO...
               ]
       error:  null


get_repo_settings 
-----------------

.. py:function:: get_repo_settings(apiuser, repoid, key=<Optional:None>)

   Returns all settings for a repository. If key is given it only returns the
   setting identified by the key or null.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: The repository name or repository id.
   :type repoid: str or int
   :param key: Key of the setting to return.
   :type: key: Optional(str)

   Example output:

   .. code-block:: bash

       {
           "error": null,
           "id": 237,
           "result": {
               "extensions_largefiles": true,
               "hooks_changegroup_push_logger": true,
               "hooks_changegroup_repo_size": false,
               "hooks_outgoing_pull_logger": true,
               "phases_publish": "True",
               "rhodecode_hg_use_rebase_for_merging": true,
               "rhodecode_pr_merge_enabled": true,
               "rhodecode_use_outdated_comments": true
           }
       }


get_repos 
---------

.. py:function:: get_repos(apiuser)

   Lists all existing repositories.

   This command can only be run using an |authtoken| with admin rights,
   or users with at least read rights to |repos|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser

   Example output:

   .. code-block:: bash

       id : <id_given_in_input>
       result: [
                 {
                   "repo_id" :          "<repo_id>",
                   "repo_name" :        "<reponame>"
                   "repo_type" :        "<repo_type>",
                   "clone_uri" :        "<clone_uri>",
                   "private": :         "<bool>",
                   "created_on" :       "<datetimecreated>",
                   "description" :      "<description>",
                   "landing_rev":       "<landing_rev>",
                   "owner":             "<repo_owner>",
                   "fork_of":           "<name_of_fork_parent>",
                   "enable_downloads":  "<bool>",
                   "enable_locking":    "<bool>",
                   "enable_statistics": "<bool>",
                 },
                 ...
               ]
       error:  null


grant_user_group_permission 
---------------------------

.. py:function:: grant_user_group_permission(apiuser, repoid, usergroupid, perm)

   Grant permission for a user group on the specified repository,
   or update existing permissions.

   This command can only be run using an |authtoken| with admin
   permissions on the |repo|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: Set the repository name or repository ID.
   :type repoid: str or int
   :param usergroupid: Specify the ID of the user group.
   :type usergroupid: str or int
   :param perm: Set the user group permissions using the following
       format: (repository.(none|read|write|admin))
   :type perm: str

   Example output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : {
       "msg" : "Granted perm: `<perm>` for group: `<usersgroupname>` in repo: `<reponame>`",
       "success": true

     }
     error :  null

   Example error output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : null
     error :  {
       "failed to edit permission for user group: `<usergroup>` in repo `<repo>`'
     }


grant_user_permission 
---------------------

.. py:function:: grant_user_permission(apiuser, repoid, userid, perm)

   Grant permissions for the specified user on the given repository,
   or update existing permissions if found.

   This command can only be run using an |authtoken| with admin
   permissions on the |repo|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: Set the repository name or repository ID.
   :type repoid: str or int
   :param userid: Set the user name.
   :type userid: str
   :param perm: Set the user permissions, using the following format
       ``(repository.(none|read|write|admin))``
   :type perm: str

   Example output:

   .. code-block:: bash

       id : <id_given_in_input>
       result: {
                 "msg" : "Granted perm: `<perm>` for user: `<username>` in repo: `<reponame>`",
                 "success": true
               }
       error:  null


invalidate_cache 
----------------

.. py:function:: invalidate_cache(apiuser, repoid, delete_keys=<Optional:False>)

   Invalidates the cache for the specified repository.

   This command can only be run using an |authtoken| with admin rights to
   the specified repository.

   This command takes the following options:

   :param apiuser: This is filled automatically from |authtoken|.
   :type apiuser: AuthUser
   :param repoid: Sets the repository name or repository ID.
   :type repoid: str or int
   :param delete_keys: This deletes the invalidated keys instead of
       just flagging them.
   :type delete_keys: Optional(``True`` | ``False``)

   Example output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : {
       'msg': Cache for repository `<repository name>` was invalidated,
       'repository': <repository name>
     }
     error :  null

   Example error output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : null
     error : {
        'Error occurred during cache invalidation action'
     }


lock 
----

.. py:function:: lock(apiuser, repoid, locked=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)

   Sets the lock state of the specified |repo| by the given user.
   From more information, see :ref:`repo-locking`.

   * If the ``userid`` option is not set, the repository is locked to the
     user who called the method.
   * If the ``locked`` parameter is not set, the current lock state of the
     repository is displayed.

   This command can only be run using an |authtoken| with admin rights to
   the specified repository.

   This command takes the following options:

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: Sets the repository name or repository ID.
   :type repoid: str or int
   :param locked: Sets the lock state.
   :type locked: Optional(``True`` | ``False``)
   :param userid: Set the repository lock to this user.
   :type userid: Optional(str or int)

   Example error output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : {
       'repo': '<reponame>',
       'locked': <bool: lock state>,
       'locked_since': <int: lock timestamp>,
       'locked_by': <username of person who made the lock>,
       'lock_reason': <str: reason for locking>,
       'lock_state_changed': <bool: True if lock state has been changed in this request>,
       'msg': 'Repo `<reponame>` locked by `<username>` on <timestamp>.'
       or
       'msg': 'Repo `<repository name>` not locked.'
       or
       'msg': 'User `<user name>` set lock state for repo `<repository name>` to `<new lock state>`'
     }
     error :  null

   Example error output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : null
     error :  {
       'Error occurred locking repository `<reponame>`
     }


pull 
----

.. py:function:: pull(apiuser, repoid)

   Triggers a pull on the given repository from a remote location. You
   can use this to keep remote repositories up-to-date.

   This command can only be run using an |authtoken| with admin
   rights to the specified repository. For more information,
   see :ref:`config-token-ref`.

   This command takes the following options:

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: The repository name or repository ID.
   :type repoid: str or int

   Example output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : {
       "msg": "Pulled from `<repository name>`"
       "repository": "<repository name>"
     }
     error :  null

   Example error output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : null
     error :  {
       "Unable to pull changes from `<reponame>`"
     }


remove_field_from_repo 
----------------------

.. py:function:: remove_field_from_repo(apiuser, repoid, key)

   Removes an extra field from a repository.

   This command can only be run using an |authtoken| with at least
   write permissions to the |repo|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: Set the repository name or repository ID.
   :type repoid: str or int
   :param key: Set the unique field key for this repository.
   :type key: str


revoke_user_group_permission 
----------------------------

.. py:function:: revoke_user_group_permission(apiuser, repoid, usergroupid)

   Revoke the permissions of a user group on a given repository.

   This command can only be run using an |authtoken| with admin
   permissions on the |repo|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: Set the repository name or repository ID.
   :type repoid: str or int
   :param usergroupid: Specify the user group ID.
   :type usergroupid: str or int

   Example output:

   .. code-block:: bash

       id : <id_given_in_input>
       result: {
                 "msg" : "Revoked perm for group: `<usersgroupname>` in repo: `<reponame>`",
                 "success": true
               }
       error:  null


revoke_user_permission 
----------------------

.. py:function:: revoke_user_permission(apiuser, repoid, userid)

   Revoke permission for a user on the specified repository.

   This command can only be run using an |authtoken| with admin
   permissions on the |repo|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: Set the repository name or repository ID.
   :type repoid: str or int
   :param userid: Set the user name of revoked user.
   :type userid: str or int

   Example error output:

   .. code-block:: bash

       id : <id_given_in_input>
       result: {
                 "msg" : "Revoked perm for user: `<username>` in repo: `<reponame>`",
                 "success": true
               }
       error:  null


set_repo_settings 
-----------------

.. py:function:: set_repo_settings(apiuser, repoid, settings)

   Update repository settings. Returns true on success.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: The repository name or repository id.
   :type repoid: str or int
   :param settings: The new settings for the repository.
   :type: settings: dict

   Example output:

   .. code-block:: bash

       {
           "error": null,
           "id": 237,
           "result": true
       }


strip 
-----

.. py:function:: strip(apiuser, repoid, revision, branch)

   Strips the given revision from the specified repository.

   * This will remove the revision and all of its decendants.

   This command can only be run using an |authtoken| with admin rights to
   the specified repository.

   This command takes the following options:

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: The repository name or repository ID.
   :type repoid: str or int
   :param revision: The revision you wish to strip.
   :type revision: str
   :param branch: The branch from which to strip the revision.
   :type branch: str

   Example output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : {
       "msg": "'Stripped commit <commit_hash> from repo `<repository name>`'"
       "repository": "<repository name>"
     }
     error :  null

   Example error output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : null
     error :  {
       "Unable to strip commit <commit_hash> from repo `<repository name>`"
     }


update_repo 
-----------

.. py:function:: update_repo(apiuser, repoid, name=<Optional:None>, owner=<Optional:<OptionalAttr:apiuser>>, group=<Optional:None>, fork_of=<Optional:None>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, fields=<Optional:''>)

   Updates a repository with the given information.

   This command can only be run using an |authtoken| with at least
   write permissions to the |repo|.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param repoid: repository name or repository ID.
   :type repoid: str or int
   :param name: Update the |repo| name.
   :type name: str
   :param owner: Set the |repo| owner.
   :type owner: str
   :param group: Set the |repo| group the |repo| belongs to.
   :type group: str
   :param fork_of: Set the master |repo| name.
   :type fork_of: str
   :param description: Update the |repo| description.
   :type description: str
   :param private: Set the |repo| as private. (True | False)
   :type private: bool
   :param clone_uri: Update the |repo| clone URI.
   :type clone_uri: str
   :param landing_rev: Set the |repo| landing revision. Default is
       ``tip``.
   :type landing_rev: str
   :param enable_statistics: Enable statistics on the |repo|,
       (True | False).
   :type enable_statistics: bool
   :param enable_locking: Enable |repo| locking.
   :type enable_locking: bool
   :param enable_downloads: Enable downloads from the |repo|,
       (True | False).
   :type enable_downloads: bool
   :param fields: Add extra fields to the |repo|. Use the following
       example format: ``field_key=field_val,field_key2=fieldval2``.
       Escape ', ' with \,
   :type fields: str