<< Back to GForge REST API

Entity: Scm

GET

getBranch

Lists the branches available in this repository, or returns info about a specific branch.

Parameters (2)

Name Type Description
name string If provided in the request path, the exact name for a single branch to be returned.
filter string Simple "starts with" filtering. If both $name and $filter are specified, then $name is used.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \gforge\plugins\tracker\models\api\ScmBranch

Zero or more ScmBranch records for a search. Zero or one ScmBranch record for a name retrieval.

Example 1

List the branches:
  GET http://api.mygforge.tld/scm/{unixName}/branch

{"paging":{"page_size":10,"page_num":1,"sort_field":"id","sort_dir":"asc"},"items":[{"name":"add_gitwebjs_gitignore#23837","type":"branch"},{"name":"angularjs","type":"branch"},{"name":"api#20980","type":"branch"},{"name":"api-ga-#19613","type":"branch"},{"name":"api-jsfooter-#19558","type":"branch"},{"name":"apidoc-css-#21234","type":"branch"},{"name":"atmel-master","type":"branch"},{"name":"audit-text-fields-#23878","type":"branch"},{"name":"auto_close_#15134","type":"branch"},{"name":"autoapproveproject#25365","type":"branch"}],"links":[]}
Note: Branches are always sorted by name (asc). There are no other sort fields.

Example 2

Get a single branch by name:
  GET http://api.mygforge.tld/scm/{unixName}/branch/gforge-next

{"name":"gforge-next","type":"branch"}

Example 3

Get branches that begin with next:
  GET http://api.mygforge.tld/scm/{unixName}/branch/?filter=next

{"paging":{"page_size":10,"page_num":1,"sort_field":"id","sort_dir":"asc"},"items":[{"name":"next\/activitytype-filter#24004","type":"branch"},{"name":"next\/angular_files_#20823","type":"branch"},{"name":"next\/anon-ti-edit-redirect-#24330","type":"branch"},{"name":"next\/anonymous-poll-query-#24322","type":"branch"},{"name":"next\/audit-display-net-#23881","type":"branch"},{"name":"next\/avatar-mydashboard-bug#23838","type":"branch"},{"name":"next\/avatar-none-bug#23841","type":"branch"},{"name":"next\/beta-users-mailchimp-#25079","type":"branch"},{"name":"next\/blockquoyed-text-#24966","type":"branch"},{"name":"next\/burndown-rendering-#24261","type":"branch"}],"links":[]}

getComment

Get the comments associated with any commits between the from and to parameters. Used to retrieve the existing comments for a proposed merge. Route: /api/scm/{id-unixname}/comments?from=&to=

Parameters (3)

Name Type Description
id mixed Database ID or unix name for the project being searched. Provided in the URI.
from string The branch, tag or commit containing the proposed changes for the merge.
to string The branch, tag or commit to which changes would be merged.

Return: \ScmMergeComment[]

Zero or more comments for the specified range of commits.

getCommit

Parameters (3)

Name Type Description
id string Unix name or database ID for the project whose git repository will be queried.
branch|tag|commit string The branch, tag or commit (in that order of preference) to be queried.
path(s) string|bool If not empty, the specific path and file name for which commits should be retrieved.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Related Entities (1)

Return: \gforge\plugins\scm\models\api\ScmCommitBasic[]

Zero or more records.

getFile

Get the properties for a single file, on the specified branch, tag, or commit. Route: /api/scm/{id-unixname}/file/zero/or/more/paths?branch=&tag=&commit=

Parameters (0)

Name Type Description
No parameters

Related Entities (2)

Return: \gforge\plugins\scm\models\api\ScmFile

Basic info about the file

Name Type Description
name string
type string
mode string
size int
isBinary string
id string

getMerge

Get information about the differences between two revisions Route: /api/scm/{id-unixname}/merge?from=&to=&rel=

Parameters (2)

Name Type Description
commitishFrom string The branch, tag or commit containing the proposed changes for the merge. This is part of the request route.
commitishTo string The branch, tag or commit to which changes would be merged. This is part of the request route.

Related Entities (2)

Return: \gforge\plugins\scm\models\api\ScmMerge

Information about the proposed merge.

Name Type Description
from string
to string
rel array
meta \StdClass for attributes about the merge itself. Fields:
  • canMerge: If true, then an automated merge can be done cleanly.
  • isMerged: If true, then the $from branch is already completely merged to the $to branch
  • fileLines: If true, then one or more files delivered in the response had too many lines and was truncated
  • fileLinesLimit: The configured max # of lines that a single file can contain
  • fileSize: If true, then one or more files delivered in the response was too long and was truncated
  • fileSizeLimit: The configured max size (in bytes) that a single file can contain
  • diffLines: If true, then the total number of source lines delivered in the response was too long and was truncated
  • diffLinesLimit: The configured max # of lines that the entire diff can contain (across all files)
  • diffSize: If true, then the total size of all files in the response was too large and was truncated
  • diffSizeLimit: The configured max size (in bytes) that the entire diff can contain (across all files)
  • diffCount: If true, then the diff contained too many individual files and was truncated
  • diffCountLimit: The configured max # of files that the diff can contain
  • commitCount: If true, then the too many individual commits were returned, and the list was truncated
  • diffCountLimit: The configured max # of commits allowed

getPromotionModel

Get the promotion model associated with this repository.

Parameters (1)

Name Type Description
id no type Database ID or unix name for the project being searched.

Return: \array(of

string) The list of promotion branches to be tracked.

getRaw

Get the raw content for a single file, on the specified branch, tag, or commit. Route: /api/scm/{id-unixname}/raw/zero/or/more/paths?branch=&tag=&commit=

Parameters (0)

Name Type Description
No parameters

Return: string

The contents of the requested file & version.

getRequestTree

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters

Return: string

The path elements from the request, separated by / characters.

getScm

Return basic information about the SCM configuration for the specified project unix name or ID.

Parameters (0)

Name Type Description
No parameters

Return: \gforge\plugins\scm\models\api\ScmBasic

Zero or one ScmBasic record for the specified project.

Name Type Description
unixName string
scmType string
defaultBranchName string
hostName string
options \StdClass for settings on the scm repo Fields:
  • useSsh: If true, then ssh access is enabled for this repository.
  • anonymousRead: If true, then anonymous users can read the repository.
  • requireTrackerItem: If true, then all commits must reference a Tracker Item ID.
  • validateEmail: If true, then all committer emails must belong to an authorized GForge user.
  • mailCommits: If true, then project members will receive email notifications about commits.
  • accessText: Optional custom text to be shown in the SCM access UI section.
  • browseText: Optional custom text to be shown in the SCM browse UI section.

Example 1

Get SCM info for a project with unix name = myproject
  GET http://api.mygforge.tld/api/scm/myproject

  {"unixName":"myproject","scmType":"git","defaultBranchName":"master","hostName":"gforge.com","options":{"useSsh":false,"anonymousRead":true,"requireTrackerItemId":false,"mailCommits":false}}

Example 2

Get SCM info for a project with database ID = 12345
  GET http://api.mygforge.tld/api/scm/12345

  {"unixName":"myproject","scmType":"git","defaultBranchName":"master","hostName":"gforge.com","options":{"useSsh":false,"anonymousRead":true,"requireTrackerItemId":false,"mailCommits":false}}

getSummary

Get a summary of activity data for the specified project's SCM, over the specified (or default) date range

NOTE: The date range will be filled in by day, even if no data is found for that day, so that the array is continuous across the specified range.

Parameters (4)

Name Type Description
id mixed The int ID or unix name for the desired project, by default from the request path (i.e., /api/scm/unixname/summary).
start string The start date/time for activity data to be returned. If empty or false, defaults to two weeks ago.
end string The end date/time for activity data. If empty or false, defaults to tomorrow.
by_user string If set to any value (e.g., 1, true, Y, whatever you've got), then return a record for each user for each day.

Related Entities (3)

Return: \gforge\plugins\scm\models\api\ScmSummary

The summary data, including a stats array with date, checkouts, commits and adds. Not all values are valid for all SCM types, may be empty or zero.

Name Type Description
stats \gforge\core\models\api\StatsBasic[] Commit stats for the repository. NOTE: If the summary was requested with the chart parameter, then this will be an array of StdClass objects, with data optimized for chart display.
totalCommits int
startDate string The date, in Y-m-d format
endDate string The date, in Y-m-d format
unixName string
scmType string
defaultBranchName string
hostName string
options \StdClass for settings on the scm repo Fields:
  • useSsh: If true, then ssh access is enabled for this repository.
  • anonymousRead: If true, then anonymous users can read the repository.
  • requireTrackerItem: If true, then all commits must reference a Tracker Item ID.
  • validateEmail: If true, then all committer emails must belong to an authorized GForge user.
  • mailCommits: If true, then project members will receive email notifications about commits.
  • accessText: Optional custom text to be shown in the SCM access UI section.
  • browseText: Optional custom text to be shown in the SCM browse UI section.

getTag

Lists the tags available in this repository, or returns info about a specific tag.

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters
Sortable
Use the sort_field and sort_dir parameters to control the order in which records are returned.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \gforge\plugins\tracker\models\api\ScmBranch

Zero or more ScmBranch records for a search. Zero or one ScmBranch record for a name retrieval.

Example 1

List the tags:
  GET http://api.mygforge.tld/scm/{unixName}/tag

{"paging":{"page_size":115,"page_num":1,"sort_field":"id","sort_dir":"asc"},"items":[{"name":"6_0b2","type":"tag"},{"name":"V5_7_ce","type":"tag"},{"name":"V5_7texinst","type":"tag"},{"name":"V_5_2_6","type":"tag"},{"name":"ge-6.1.0","type":"tag"},{"name":"ge-v6.1.2","type":"tag"},{"name":"ge_6.0.2","type":"tag"},{"name":"noaa_5.2.4.5","type":"tag"},{"name":"raytheon-6.1.2","type":"tag"},{"name":"raytheon-6.1.3-alpha1","type":"tag"},{"name":"raytheon-6.1.3-beta1","type":"tag"},{"name":"raytheon-6.1.3b1","type":"tag"},{"name":"remove","type":"tag"},{"name":"sandia_5_2_7b","type":"tag"},{"name":"siemens-v6.3.1","type":"tag"},{"name":"v5_0","type":"tag"},{"name":"v5_0_1","type":"tag"},{"name":"v5_0_2","type":"tag"},{"name":"v5_0_3","type":"tag"},{"name":"v5_1","type":"tag"},{"name":"v5_1_1","type":"tag"},{"name":"v5_1_2","type":"tag"},{"name":"v5_1_3","type":"tag"},{"name":"v5_1_4","type":"tag"},{"name":"v5_1_a","type":"tag"},{"name":"v5_2","type":"tag"},{"name":"v5_2_1","type":"tag"},{"name":"v5_2_2","type":"tag"},{"name":"v5_2_4","type":"tag"},{"name":"v5_2_5","type":"tag"},{"name":"v5_2_6","type":"tag"},{"name":"v5_2_6b","type":"tag"},{"name":"v5_2_7","type":"tag"},{"name":"v5_2_7b","type":"tag"},{"name":"v5_3","type":"tag"},{"name":"v5_3_1","type":"tag"},{"name":"v5_3_2","type":"tag"},{"name":"v5_3_2_siemens","type":"tag"},{"name":"v5_3_2_siemens2","type":"tag"},{"name":"v5_3_3","type":"tag"},{"name":"v5_3b1","type":"tag"},{"name":"v5_3b3","type":"tag"},{"name":"v5_3b4","type":"tag"},{"name":"v5_3b5","type":"tag"},{"name":"v5_4_1","type":"tag"},{"name":"v5_4_1ge","type":"tag"},{"name":"v5_4_1noaa","type":"tag"},{"name":"v5_4_1sandia","type":"tag"},{"name":"v5_4_1siemens","type":"tag"},{"name":"v5_4_2","type":"tag"},{"name":"v5_4_2ge","type":"tag"},{"name":"v5_4_3","type":"tag"},{"name":"v5_4_4","type":"tag"},{"name":"v5_4_ge_b1","type":"tag"},{"name":"v5_4_noaa-final","type":"tag"},{"name":"v5_4_sandia","type":"tag"},{"name":"v5_4_siemens","type":"tag"},{"name":"v5_4fb","type":"tag"},{"name":"v5_4fb2","type":"tag"},{"name":"v5_4noaa","type":"tag"},{"name":"v5_5","type":"tag"},{"name":"v5_5_1","type":"tag"},{"name":"v5_5b2","type":"tag"},{"name":"v5_5b3","type":"tag"},{"name":"v5_5raytheon","type":"tag"},{"name":"v5_5rc1","type":"tag"},{"name":"v5_5rc2","type":"tag"},{"name":"v5_5sandia","type":"tag"},{"name":"v5_5siemens","type":"tag"},{"name":"v5_6","type":"tag"},{"name":"v5_6_1","type":"tag"},{"name":"v5_6_1_asterisk","type":"tag"},{"name":"v5_6a","type":"tag"},{"name":"v5_6rc2","type":"tag"},{"name":"v5_6rc3","type":"tag"},{"name":"v5_6rc4","type":"tag"},{"name":"v5_7","type":"tag"},{"name":"v5_7_1","type":"tag"},{"name":"v5_7_1_b1_cisco","type":"tag"},{"name":"v5_7_1_b1_oracle","type":"tag"},{"name":"v5_7_1_ge","type":"tag"},{"name":"v5_7_1_raytheon","type":"tag"},{"name":"v5_7_1_siemens","type":"tag"},{"name":"v5_7_1_texinst","type":"tag"},{"name":"v5_7_1ge","type":"tag"},{"name":"v5_7_2","type":"tag"},{"name":"v5_7_2_ge","type":"tag"},{"name":"v5_7_2_raytheon","type":"tag"},{"name":"v5_7_b2_ge","type":"tag"},{"name":"v5_7_ge","type":"tag"},{"name":"v5_7_raytheon","type":"tag"},{"name":"v5_7_sandia","type":"tag"},{"name":"v5_7_siemens","type":"tag"},{"name":"v5_7b1","type":"tag"},{"name":"v5_7b1_oracle","type":"tag"},{"name":"v5_7ce","type":"tag"},{"name":"v5_7rc1","type":"tag"},{"name":"v5_7rc1-ce","type":"tag"},{"name":"v5_7texinst","type":"tag"},{"name":"v6.0.3","type":"tag"},{"name":"v6.1","type":"tag"},{"name":"v6.1.1","type":"tag"},{"name":"v6.1.2","type":"tag"},{"name":"v6.2","type":"tag"},{"name":"v6.2.1","type":"tag"},{"name":"v6.3.0","type":"tag"},{"name":"v6.3.1","type":"tag"},{"name":"v6.4.0","type":"tag"},{"name":"v6.4.1","type":"tag"},{"name":"v6_0_1","type":"tag"},{"name":"v6_0b1","type":"tag"},{"name":"v6_0b2","type":"tag"},{"name":"v6_1b1","type":"tag"},{"name":"v6_1b2","type":"tag"},{"name":"v_5_2_5","type":"tag"}],"links":[]}

Example 2

Get a single tag by name:
  GET http://api.mygforge.tld/scm/{unixName}/tag/{branchname}

{"name":"6_0b2","type":"tag"}

Example 3

Get tags that begin with v (e.g., v1.0, v0.1):
  GET http://api.mygforge.tld/scm/{unixName}/tag/?filter=v

{"paging":{"page_size":10,"page_num":1,"sort_field":"id","sort_dir":"asc"},"items":[{"name":"V5_7_ce","type":"tag"},{"name":"V5_7texinst","type":"tag"},{"name":"V_5_2_6","type":"tag"},{"name":"v5_0","type":"tag"},{"name":"v5_0_1","type":"tag"},{"name":"v5_0_2","type":"tag"},{"name":"v5_0_3","type":"tag"},{"name":"v5_1","type":"tag"},{"name":"v5_1_1","type":"tag"},{"name":"v5_1_2","type":"tag"}],"links":[]}

getTree

Get the list of files and folders associated with the specified branch, tag, commit and tree path. Route: /api/scm/{id-unixname}/tree/zero/or/more/paths?branch=&tag=&commit=

Parameters (0)

Name Type Description
No parameters

Return: \gforge\plugins\scm\models\api\ScmFile[]

Zero or more files and folders

POST

postComment

Add a comment to the specified commit, file and line. A new record will always be created. Used to create a comment for a proposed merge. Route: /api/scm/{id-unixname}/comment/{comment-id}

Parameters (7)

Name Type Description
id mixed Database ID or unix name for the project being searched. Provided in the URI.
commitId int Database ID for an existing comment. Provided in the URI. Optional.
commit string SCM-assigned identifier for the associated commit.
file string The path and file name of the code being commented on.
line int The line number being commented on, within the specified file.
body string The comment text.
context string An optional snippet of diff data, to be preserved for future reference as the commented code may change.

Return: \URI

to the newly-created comment, or a set of validation error(s).

postMerge

Merge one set of changes into another branch/tag/revision. Route: /api/scm/{id-unixname}/merge?from=&to=&rel=

Parameters (2)

Name Type Description
from string The branch, tag or commit containing the proposed changes for the merge. This is part of the request route.
to string The branch, tag or commit to which changes would be merged. This is part of the request route.

Related Entities (2)

Return: \gforge\plugins\scm\models\api\ScmMerge

Information about the proposed merge.

Name Type Description
from string
to string
rel array
meta \StdClass for attributes about the merge itself. Fields:
  • canMerge: If true, then an automated merge can be done cleanly.
  • isMerged: If true, then the $from branch is already completely merged to the $to branch
  • fileLines: If true, then one or more files delivered in the response had too many lines and was truncated
  • fileLinesLimit: The configured max # of lines that a single file can contain
  • fileSize: If true, then one or more files delivered in the response was too long and was truncated
  • fileSizeLimit: The configured max size (in bytes) that a single file can contain
  • diffLines: If true, then the total number of source lines delivered in the response was too long and was truncated
  • diffLinesLimit: The configured max # of lines that the entire diff can contain (across all files)
  • diffSize: If true, then the total size of all files in the response was too large and was truncated
  • diffSizeLimit: The configured max size (in bytes) that the entire diff can contain (across all files)
  • diffCount: If true, then the diff contained too many individual files and was truncated
  • diffCountLimit: The configured max # of files that the diff can contain
  • commitCount: If true, then the too many individual commits were returned, and the list was truncated
  • diffCountLimit: The configured max # of commits allowed

postPromotionModel

Update the promotion model associated with this repository

Parameters (2)

Name Type Description
id no type Database ID or unix name for the project being searched.
branches no type A comma-separated list of branch names as the model.

Return: string

The updated model

postScm

Update the SCM configuration for the specified project. The entire ScmBasic object is expected, but only values in the options sub-object will be updated.

Parameters (2)

Name Type Description
id int|string Identifier for the project, part of the route. Can be the ID (int) or unixName (string).
options \StdClass

Return: void

No return type is defined

PUT

putSshKeys

Parameters (1)

Name Type Description
requestParameters \mvcnphp\RequestParameters

Return: (none)

No return type is defined

DELETE