UAPI Functions - VersionControl::retrieve

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.

Important:

This feature does not allow the following characters in repository paths:
```
\ * | " ' < > & @ ` $ { } [ ] ( ) ; ? : = % #
```
This function does not allow repositories that exist in the following cPanel-controlled directories:
Click to view...
- .cpanel
- .cphorde
- .htpasswds
- .ssh
- .trash
- access-logs
- cgi-bin
- etc
- logs
- perl5
- mail
- spamassassin
- ssl
- tmp
- var

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.

Examples

cPanel or Webmail Session URL

https://hostname.example.com:2083/cpsess##########/execute/VersionControl/retrieve?fields=name,type,branch,last_update

Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation.

LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List the account's repositories.
$templates = $cpanel->uapi(
    'VersionControl', 'retrieve',
     array(
        'fields' => 'name,type,branch,last_update',
     )
);

Note:

For more information, read our Guide to the LiveAPI System.

LiveAPI Perl Module

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# List the account's repositories.
my $templates = $cpliveapi->uapi(
    'VersionControl', 'retrieve', {
         'fields' => 'name,type,branch,last_update',
    }
);

Note:

For more information, read our Guide to the LiveAPI System.

cPanel Template Toolkit

<!-- List the account's repositories. -->
[% execute( 'VersionControl', 'retrieve', { 'fields' => 'name,type,branch,last_update' } ); %]

Note:

For more information, read our Guide to Template Toolkit documentation.

Command Line

uapi --user=username VersionControl retrieve fields=name,type,branch,last_update

Notes:

You must URI-encode values.
username represents your account-level username.
For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command.
If you run CloudLinux™, you must use the full path of the uapi command:
```
/usr/local/cpanel/bin/uapi
```

Output (JSON)

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

Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

Parameter Type Description Possible values Example

fields

string

A list of desired return values.

This parameter defaults to *.

A comma-separated list of returns.
* — List all possible returns.

name,type,branch,last_update

Returns

Return	Type	Description	Possible values	Example
	hash	An unnamed hash of repository data.	This hash includes the `type`, `repository_root`, `branch`, and `name` returns, the `available_branches` array, and the `last_update`, `source_repository`, and `clone_urls` hashes.
`name`	string	The repository's display name. The function returns this value in the repository's hash.	A valid string.	`example`
`type`	string	The repository type. The function returns this value in the repository's hash.	`git` is the only possible value.	`git`
`repository_root`	string	The directory that contains the repository. The function returns this value in the repository's hash.	A valid absolute path to a directory that exists within the user's home directory.	`/home/user/public_html/example`
`branch`	string	The repository's current branch. The function returns this value in the repository's hash.	A valid branch name. `null` — The system has not finished the clone process for the repository, no local branches exist, or the repository is a bare repository.	`master`
`deployable`	Boolean	Whether the system could deploy the repository. Note: We added this return in cPanel & WHM version 74.	`1` — Can deploy. `0` — Cannot deploy.	`1`
`source_repository`	hash	A hash of information about the source repository. Note: The function only returns this hash if you cloned a source repository. The function returns this hash in the repository's hash.	This hash contains the `remote_name` and `url` parameters. Important: You must JSON-encode the contents of this hash.
`remote_name`	JSON string	The source repository's name. The function returns this value in the `source_repository` hash.	A valid JSON-encoded string.	`origin`
`url`	JSON string	The source repository's clone URL. Note: If you include the `source_repository` hash, you must specify a `url` value. The function returns this value in the `source_repository` hash.	A valid JSON-encoded clone URL.	`ssh://clone.domain.com/cloneme`
`available_branches`	array of strings	An array of available branches for the repository. The function returns this value in the repository's hash.	An array of local and remote branch names that exist for the cloned or existing repository. An empty array, if no branches exist. `null`, if the repository is a bare repository.	`master`
`last_update`	hash	A hash of information about the most-recent (HEAD) commit for the current branch. Note: This hash's information resembles the output of the `git log -1` command. The function returns this hash in the repository's hash.	This hash includes the `date`, `identifier`, `author`, and `message` returns. Important: If the repository does not include any commits, the function returns a `null` value instead of a hash. The system may require a large amount of time to clone larger repositories. Until this process finishes, HEAD information is unavailable.
`date`	string	The timestamp for the most-recent commit. The function returns this value in the `last_update` hash.	A time, in Unix time format.	`1410277881`
`identifier`	string	The identifier (SHA-1 value) for the most-recent commit. The function returns this value in the `last_update` hash.	A valid SHA-1 value.	`2fd4e1c67a2d28fced849ee1bb76e7391b93eb12`
`author`	string	The most-recent commit's author's name and email address. The function returns this value in the `last_update` hash.	The author's name and email address as they exist in the user's Git configuration files.	`Jane Doe <jane.doe@example.com>`
`message`	string	The commit message. The function returns this value in the `last_update` hash.	A valid string.	`I'm committing some particularly cromulent code.`
`last_deployment`	hash	A hash of information about the commit that the system most recently deployed. Notes: We added this hash in cPanel & WHM version 74. The system only returns this hash if deployment information exists. The function returns this hash in the repository's hash.	This hash includes the `deployment_date` return and the `repository_state` hash.
`deployment_date`	string	The timestamp for the most-recent deployment. Note: We added this return in cPanel & WHM version 74. The function returns this value in the `last_deployment` hash.	A time, in Unix time format.	`1410277881`
`repository_state`	hash	A hash of information about the state of the repository at the time of the most recent deployment. Note: We added this hash in cPanel & WHM version 74. The function returns this hash in the `last_deployment` hash.	This hash includes the `date`, `identifier`, `author`, and `message` returns.
`date`	string	The timestamp for the commit that the system most recently deployed. Note: We added this return in cPanel & WHM version 74. The function returns this value in the `repository_state` hash.	A time, in Unix time format.	`1410277881`
`identifier`	string	The identifier (SHA-1 value) for the commit that the system most recently deployed. Note: We added this return in cPanel & WHM version 74. The function returns this value in the `repository_state` hash.	A valid SHA-1 value.	`2fd4e1c67a2d28fced849ee1bb76e7391b93eb12`
`author`	string	The author's name and email address for the commit that the system most recently deployed. Note: We added this return in cPanel & WHM version 74. The function returns this value in the `repository_state` hash.	The author's name and email address as they exist in the user's Git configuration files.	`Jane Doe <jane.doe@example.com>`
`message`	string	The commit message for the commit that the system most recently deployed. Note: We added this return in cPanel & WHM version 74. The function returns this value in the `repository_state` hash.	A valid string.	`I'm committing some particularly cromulent code.`
`clone_urls`	hash of arrays	A hash of arrays of URLs to use to clone the repository. The function returns this hash in the repository's hash.	This hash includes the `read_write` and `read_only` arrays.
`read_write`	array	An array of clone URLs with read-write permissions. The function returns this array in the `clone_urls` hash.	One or more valid URLs. A blank array, if the account does not include the Shell Access setting. Important: If the server uses a nonstandard SSH port, the system returns a clone URL that includes the port number.	ssh://user@example.com/home/user/example
`read_only`	array	An array of clone URLs with read-only permissions. The function returns this array in the `clone_urls` hash.	One or more valid URLs. A blank array, if the account does not include the Shell Access setting. Important: If the server uses a nonstandard SSH port, the system returns a clone URL that includes the port number.	https://user@example.com/home/user/example
`tasks`	array of hashes	An array of hashes of information about the Task Queue system's process that will clone the repository. Note: The function only returns this value if the clone process is not finished. The function returns this hash in the repository's hash.	This array of hashes includes the `id` , `subsystem` , and `action` returns.
`id`	string	The Task Queue system's task ID number. The function returns this value in the `tasks` hash.	A valid process ID.	`00000000/5a9ec8dd4c345d`
`subsystem`	string	The Task Queue subsystem that will handle the task. The function returns this value in the `tasks` hash.	`VersionControl` is the only possible value.	`VersionControl`
`action`	string	The task's action. The function returns this value in the `tasks` hash.	`create` — Create the repository. `deploy` — Deploy the repository.
`sse_url`	string	The Secure Server Events (SSE) interface to track the progress of the process. Note: We added this return in cPanel & WHM version 74. The function returns this value in the `tasks` hash.	A valid SSE URL.	`/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0`
`args`	hash	A hash of arguments for the Task Queue system's process. Note: We added this return in cPanel & WHM version 74. The function returns this value in the `action` hash.	This hash includes the `repository_root` and `log_file` returns.
`repository_root`	string	The repository's directory. Note: We added this return in cPanel & WHM version 74. The function returns this value in the `args` hash.	A valid absolute path to a directory within the user's home directory.	`/home/user/example`
`log_file`	string	The process's log file. Notes: The function only returns this value if the process generated a log file. We added this return in cPanel & WHM version 74. The function returns this value in the `args` hash.	A valid absolute path to a log file.	Click to view... `/home/username/.cpanel/logs/vc_1234567890.123456_git_deploy.log`

Function information

Module:

VersionControl

API Version:

UAPI

Available in:

cPanel 72+

Methods:

GET, POST

Required Parameters:

(none)

Return formats:

JSON

Legacy Equivalents:

(none)

About this module

The VersionControl module manages Git™ repositories.

About UAPI

UAPI accesses and modifies data for cPanel accounts.

Notes:

These functions may require specific features. To enable or disable features, use WHM's Feature Manager interface.
Unless you call this API via the WHM API, you must use the appropriate cPanel ports (2082 or 2083). You can also call some functions via cPanel's Webmail ports (2095 or 2096).

Find a function

Related functions

Page:

UAPI Modules - VersionControl — The VersionControl module manages Git™ repositories.
Page:

UAPI Functions - VersionControl::create — This function creates a new Git™ repository on a cPanel account.
Page:

UAPI Modules - VersionControlDeployment — The VersionControlDeployment module manages Git™ deployments.
Page:

UAPI Functions - VersionControlDeployment::retrieve — This function retrieves the status of deployment tasks.
Page:

UAPI Functions - VersionControlDeployment::create — This function deploys the changes from a cPanel-managed repository.

Child pages

UAPI Functions - VersionControl::retrieve

Description

Examples

Parameters

Returns

Function information

About this module

About UAPI

Find a function

Search

Related functions