Child pages
  • UAPI Functions - VersionControl::retrieve
Skip to end of metadata
Go to start of metadata

Description

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

ParameterTypeDescriptionPossible valuesExample
fieldsstring

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

ReturnTypeDescriptionPossible valuesExample

 

hashAn 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