# Return Git repositories

This function lists Git™ repositories on a cPanel account. For more information
about support for version control in cPanel & WHM, read our
Git Version Control and
Guide to Git documentation.



* This feature does  allow the following characters in repository paths:
  ` $ { } [ ] ( ) ; ? : = % #`.cpanel.htpasswds.ssh.trashaccess-logscgi-binetclogsperl5mailspamassassinssltmpvar`

Users can create repositories in some of these directories on the command line.
They may appear in the list of repositories in Gitweb, but users may see an error
message if they try to access them.

Endpoint: GET /VersionControl/retrieve
Version: 11.134.0.5
Security: BasicAuth

## Query parameters:

  - `fields` (string)
    A comma-separated list of desired return values.



Use a wildcard () to list all possible return values.
    Example: "name,type,branch,last_update"

## Response 200 fields (application/json):

  - `apiversion` (integer)
    The version of the API.
    Example: 3

  - `func` (string)
    The name of the method called.
    Example: "retrieve"

  - `module` (string)
    The name of the module called.
    Example: "VersionControl"

  - `result` (object)

  - `result.data` (array)
    An array of objects containing repository data.
    Example: [{"available_branches":["master"],"branch":"master","clone_urls":{"read_only":["https://user@example.com/home/user/example"],"read_write":["ssh://user@example.com/home/user/example"]},"deployable":1,"last_deployment":{"deployment_date":1598774400,"repository_state":{"author":"User Name <user.name@example.com>","date":1598774400,"identifier":"2fd4e1c67a2d28fced849ee1bb76e7391b93eb12","message":"I'm committing some particularly cromulent code."}},"last_update":{"author":"Jane Doe <jane.doe@example.com>","date":1598774400,"identifier":"2fd4e1c67a2d28fced849ee1bb76e7391b93eb12","message":"I'm committing some particularly cromulent code."},"name":"example","repository_root":"/home/user/example","tasks":[{"action":"create","args":{"log_file":"/home/user/.cpanel/logs/vc_1526305129.123456_git_create.log","repository_root":"/home/user/example"},"id":"00000000/5a9ec8dd4c345d","sse_url":"/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0","subsystem":"VersionControl"}],"type":"git"},{"available_branches":["master"],"branch":"master","deployable":1,"last_update":{"author":"June Due <june.due@example2.com>","clone_urls":{"read_only":["https://user@example.com/home/user/example"],"read_write":["ssh://user@example.com/home/user/example"]},"date":1599730200,"identifier":"4ee0b73ddf78213c41fcc185acfab68ced99046d","last_deployment":{"deployment_date":1599730200,"repository_state":{"author":"User Name <user.name@example.com>","date":1599730200,"identifier":"2fd4e1c67a2d28fced849ee1bb76e7391b93eb12","message":"I'm committing some particularly cromulent code."}},"message":"My code makes more sense, actually.","tasks":[{"action":"create","args":{"log_file":"/home/user/.cpanel/logs/vc_1526305129.123456_git_create.log","repository_root":"/home/user/example"},"id":"00000000/5a9ec8dd4c345d","sse_url":"/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0","subsystem":"VersionControl"}]},"name":"example2","repository_root":"/home/user/example2","type":"git"}]

  - `result.data.available_branches` (array,null)
    A list of available local and remote branches for the cloned
or existing repository.

* An empty array — No branches exist.
*  — The repository is a bare repository.

  - `result.data.branch` (string,null)
    The repository's current branch.

*  — The system has not finished the clone process for the
repository, no local branches exist, or the repository is a bare
repository.

  - `result.data.clone_urls` (object)
    An array of objects containing URLS to use to clone the repository.

  - `result.data.clone_urls.read_only` (array)
    A list of clone URLs with read-only permissions.

This function returns a blank array if the account does
not include the  setting.



If the server uses a nonstandard SSH port, the system returns a
clone URL that includes the port number.

  - `result.data.clone_urls.read_write` (array)
    A list of clone URLs with read-write permissions.

This function returns a blank array if the account does
not include the  setting.



If the server uses a nonstandard SSH port, the system returns a
clone URL that includes the port number.

  - `result.data.deployable` (integer)
    Whether the system could deploy the repository.

*  — Can deploy.
*  — Cannot deploy.
    Enum: 1, 0

  - `result.data.last_deployment` (object)
    An object containing information about the commit that the system
most recently deployed.



The system  returns this object if deployment information
exists.

  - `result.data.last_deployment.deployment_date` (integer)
    The timestamp for the most-recent deployment.

  - `result.data.last_deployment.repository_state` (object)
    A object containing information about the state of the repository at the time of the most recent deployment.

  - `result.data.last_deployment.repository_state.author` (string)
    The author's name and email address for the commit that the system most recently deployed.

  - `result.data.last_deployment.repository_state.date` (integer)
    The timestamp for the commit that the system most recently deployed.

  - `result.data.last_deployment.repository_state.identifier` (string)
    The identifier (SHA-1 value) for the commit that the system most recently deployed.

  - `result.data.last_deployment.repository_state.message` (string)
    The commit message for the commit that the system most recently deployed.

  - `result.data.last_update` (object,null)
    An object containing information about the most-recent (HEAD) commit
for the current branch. 



This object's information resembles the output of the 
command.



* If the repository does not include any commits, the function returns
a  value instead of an object.
* The system may require a large amount of time to clone larger
repositories. Until this process finishes, HEAD information is
unavailable.

  - `result.data.last_update.author` (string)
    The most-recent commit's author's name and email address.
    Example: "Jane Doe <jane.doe@example.com>"

  - `result.data.last_update.date` (integer)
    The timestamp for the most-recent commit.
    Example: 1569844800

  - `result.data.last_update.identifier` (string)
    The identifier (SHA-1 value) for the most-recent commit.
    Example: "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"

  - `result.data.last_update.message` (string)
    The commit message.
    Example: "I'm committing some particularly cromulent code."

  - `result.data.name` (string)
    The repository's display name.
    Example: "example"

  - `result.data.repository_root` (string)
    The absolute directory path in the user's  directory containing the repository.
    Example: "/home/user/public_html/example"

  - `result.data.source_repository` (object)
    An object containing information about the source repository.



The function  returns this object if you cloned a source
repository.

  - `result.data.source_repository.remote_name` (string)
    The source repository's name.
    Example: "origin"

  - `result.data.source_repository.url` (string)
    The source repository's clone URL.
    Example: "ssh://clone.domain.com/cloneme"

  - `result.data.tasks` (array)
    An array of objects containing information about the
[Task Queue](https://go.cpanel.net/whmdocsTaskQueueMonitor)
system's process that will clone the repository.



The function only returns this value if the clone process is
 finished.

  - `result.data.tasks.action` (string)
    The task's action.

*  — Create the repository.
*  — Deploy the repository.
    Enum: "create", "deploy"

  - `result.data.tasks.args` (object)
    A list of arguments for the Task Queue system's process.

  - `result.data.tasks.args.log_file` (string)
    The absolute path to the process's log file.



The function only returns this value if the process generated
a log file.
    Example: "/home/username/.cpanel/logs/vc_1234567890.123456_git_deploy.log"

  - `result.data.tasks.args.repository_root` (string)
    The absolute path to the repository's directory in the user's  directory.
    Example: "/home/user/example"

  - `result.data.tasks.id` (string)
    The Task Queue system's task ID number.
    Example: "00000000/5a9ec8dd4c345d"

  - `result.data.tasks.sse_url` (string)
    The Secure Server Events (SSE) interface URL to track the progress of the process.
    Example: "/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0"

  - `result.data.tasks.subsystem` (string)
    The Task Queue subsystem that will handle the task.

*  is the only possible value.
    Enum: "VersionControl"

  - `result.data.type` (string)
    The repository type.

*  is the only possible value.
    Enum: "git"

  - `result.errors` (array,null)
    List of errors if the API failed.

  - `result.messages` (array,null)
    List of messages generated by the API.

  - `result.metadata` (object)

  - `result.metadata.transformed` (integer)
    Post-processing may have transformed the data.
    Enum: 1

  - `result.status` (integer)
    *  — Success.
*  — Failed. Check the  field for more details.
    Enum: 1, 0

  - `result.warnings` (array,null)
    List of warnings generated by the API. Warnings describe non-critical failures or other problematic conditions noted while running a API.