Difference between revisions of "Orion/Server API/Git API"

Revision as of 06:39, 24 June 2011

The Git API is a web server API for browsing and manipulating Git repositories.

git URIs format change
Please note, that once bug 339854 is fixed all URIs listed below will have a slightly different form. I will try to update the page ASAP.

Git commands

git add

• #Staging files
• #Unstaging files
• #Getting a file content from index

git branch

see bug 341384

git checkout

see bug 337818

git clone

see bug 337818

git config

#Configuring git

git commit

• #Committing files in index
• #Amending a commit
• Committing a single file

git diff

• #Getting a diff between working tree and index
• #Getting a diff between index and HEAD
• #Getting a diff location for two commits
• #Getting a diff between two commits
• #Getting a file content from index
• #Getting a file content from HEAD

git fetch

• #Fetching changes from a remote

see bug 339110

git log

• #Getting a git log

see bug 339104

git merge

• #Merging changes to HEAD

see bug 339111

git mv

see bug 349168

git pull

see bug 339114

git push

• #Pushing changes to a remote

see bug 339115

git remote

see bug 339109

git reset

see bug 338202

git revert

see bug 339105

git rm

see bug 349299

git status

#Getting status for a git project

git tag

• #Tagging a commit

see bug 339108

REST API

Getting the list of repositories

Overview

To get the list of repositories send a GET request to the git clone location.

HTTP Method

GET

Example Request

GET /git/clone/

  

Example Response

HTTP/1.1 200 OK

{"Children": [
 {
   "ContentLocation": "file:/C:/home/workspaces/foo/.userarea/x/.gitclone/d",
   "Id": "d",
   "Location": "http://localhost:8080/git/clone/d",
   "Name": "c:\\home\\clones\\testClone"
 },
 {
   "ContentLocation": "file:/C:/home/workspaces/foo/.userarea/x/.gitclone/b",
   "Id": "b",
   "Location": "http://localhost:8080/git/clone/b",
   "Name": "c:\\home\\clones\\testClone"
 },
 {
   "ContentLocation": "file:/C:/home/workspaces/foo/.userarea/x/.gitclone/c",
   "Id": "c",
   "Location": "http://localhost:8080/git/clone/c",
   "Name": "c:\\home\\clones\\testClone"
 },
 {
   "ContentLocation": "file:/C:/home/workspaces/foo/.userarea/x/.gitclone/a",
   "Id": "a",
   "Location": "http://localhost:8080/git/clone/a",
   "Name": "c:\\home\\clones\\testClone"
 }
 ]}

Detailed Explanation

TBD

Creating a repository clone

Overview

To create a clone send a POST request to the git clone location.

HTTP Method

POST

Example Request

POST /git/clone/

{
 "GitUrl" : "{git repo url}",
 "GitSshKnownHost" : "{git ssh known host}",
 "GitSshUsername" : "{git ssh username}",
 "GitSshPassword" : "{git ssh password}",
 "GitSshKnownHost" : "{git ssh known host}",
 "GitSshPrivateKey" : "{git ssh private key}",
 "GitSshPassphrase" : "{git ssh passphrase}"
 }  

Example Response

HTTP/1.1 201 CREATED

{
 "Id": "IOOD6ph8ABASBcDqmXX87w",
 "Location": "http://localhost:8080/task/id/IOOD6ph8ABASBcDqmXX87w",
 "Message": "Cloning c:\\home\\clones\\testClone...",
 "PercentComplete": 0,
 "Running": true
 }

Detailed Explanation

The response contains the location of the git clone task. Call Get on the task location to check the status.

Initializing a git repository

Overview

To init a git repository send a POST request to the git clone location. JSON data cannot contain GitUrl field, as it indicates that desired operation is cloning of a repository.

HTTP Method

POST

Example Request

POST /git/clone/

{
 "Name" : "d",
 "Location" : "/workspace/A",
 "Path" : "/file/d",
 }  

Example Response

HTTP/1.1 201 CREATED

{
 "Location": "http://localhost:8080/git/clone/file/d"
 }

Detailed Explanation

The response contains the location of the initialized git repository. Call Get on this location to obtain more repository details. Request body can contain either "Name" and "Location" fields (a new project with git repository will be created in the given workspace) or "Path" field only (git repository will be created in the given project).

Getting a file content from HEAD

Overview

To retrieve file content kept in HEAD. Send a GET request to the git commit location.

HTTP Method

GET

Example Request

GET /git/commit/HEAD/file/MyProj/file.txt

  

Example Response

HTTP/1.1 200 OK
 Content-Type: text/plain
 Content-Length: 22

This is the content.

Detailed Explanation

TBD.

Committing all files in index

Overview

To commit all files in index. Send a POST request to the git commit location.

HTTP Method

POST

Example Request

POST /git/commit/file/MyProj/

{
"Message" : "{Your commit message}" 
}  

Example Response

HTTP/1.1 200 OK
 Content-Type: text/plain
 Content-Length: 22

<nothing>

Detailed Explanation

TBD.

Amending a commit

Overview

To amend the last commit. Send a POST request to the git commit location.

HTTP Method

POST

Example Request

POST /git/commit/file/MyProj/

{
"Message" : "{Your (amended) commit message}",
"Amend" : "true"
}  

Example Response

HTTP/1.1 200 OK
 Content-Type: text/plain
 Content-Length: 22

<nothing>

Detailed Explanation

TBD.

Merging changes from a remote to HEAD

Overview

To merge changes from a remote to HEAD send a POST request to the git commit location.

HTTP Method

POST

Example Request

POST /git/commit/HEAD/file/E/

{
 "Merge" : "(refId)"
 }  

Example Response

HTTP/1.1 200 OK

{"Result": "ALREADY_UP_TO_DATE"}

Detailed Explanation

TBD.

Tagging a commit

Overview

To tag a commit send a PUT request to the git commit location.

HTTP Method

PUT

Example Request

PUT /git/commit/(revision)/file/MyProj/

{
 "Name" : "{tag name}" 
 }  

Example Response

HTTP/1.1 200 OK
 Content-Type: text/plain
 Content-Length: 22

{
 "AuthorName": "(author)",
 "Children": ["(tag name)"],
 "ContentLocation": "http://localhost:8080/git/commit/(revision)/file/MyProj/?parts=body",
 "DiffLocation": "http://localhost:8080/git/diff/(revision)/file/MyProj/",
 "Location": "http://localhost:8080/git/commit/(revision)/file/MyProj/",
 "Message": "(commit message)",
 "Name": "(commit name)",
 "Time": 1304073355000
 }

Detailed Explanation

TBD.

Configuring git

Progress is being tracked on bug 337820.

Getting a diff between working tree and index

Overview

To retrieve changes between working tree and index. Send a GET request to the git diff location.

HTTP Method

GET

Example Request

GET /git/diff/Default/file/MyProj/
Orion-Version: 1.0

  

Example Response

HTTP/1.1 HTTP/1.1 200 OK
Content-Type: multipart/related; boundary="BOUNDARY"
ETag: "35fd43td3"
--BOUNDARY
Content-Type: application/json

{"Git":
   {"Base":"http://localhost:8080/git/index/file/E/a.txt",
    "DiffLocation":"http://localhost:8080/git/diff/Default/file/E/a.txt",
    "New":"http://localhost:8080/file/E/a.txt",
    "Old":"http://localhost:8080/git/index/file/E/a.txt"
   }
 }

--BOUNDARY
Content-Type: plain/text

diff --git a/a.txt b/a.txt
index 380e08d..bbfd849 100644
--- a/a.txt
+++ b/a.txt
@@ -1,3 +1,4 @@
fdsfdsafdsad
asasasa2d
-Elod
+Elod
+Something

Detailed Explanation

The diff and related uris are returned as a single multi-part response. You may use query parts=uris or parts=diff to get only one part of the response.

Getting a diff between index and HEAD

Overview

To retrieve changes between index and HEAD. Send a GET request to the git diff location.

HTTP Method

GET

Example Request

GET /git/diff/Cached/file/MyProj/
Orion-Version: 1.0

  

Example Response

HTTP/1.1 HTTP/1.1 200 OK
Content-Type: multipart/related; boundary="BOUNDARY"
ETag: "35fd43td3"
--BOUNDARY
Content-Type: application/json

{"Git":
   {"Base":"http://localhost:8080/git/index/file/E/a.txt",
    "DiffLocation":"http://localhost:8080/git/diff/Default/file/E/a.txt",
    "New":"http://localhost:8080/file/E/a.txt",
    "Old":"http://localhost:8080/git/index/file/E/a.txt"
   }
 }

--BOUNDARY
Content-Type: plain/text

diff --git a/a.txt b/a.txt
index 380e08d..bbfd849 100644
--- a/a.txt
+++ b/a.txt
@@ -1,3 +1,4 @@
fdsfdsafdsad
asasasa2d
-Elod
+Elod
+Something

Detailed Explanation

The diff and related uris are returned as a single multi-part response. You may use query parts=uris or parts=diff to get only one part of the response.

Getting a diff between two commits

Overview

To retrieve changes between two commits. Send a GET request to the git diff location.

HTTP Method

GET

Example Request

GET /git/diff/{old revision}..{new revision}/file/MyProj/
Orion-Version: 1.0

  

Example Response

HTTP/1.1 HTTP/1.1 200 OK
Content-Type: multipart/related; boundary="BOUNDARY"
ETag: "35fd43td3"
--BOUNDARY
Content-Type: application/json

{"Git":
   {"Base":"http://localhost:8080/git/index/file/E/a.txt",
    "DiffLocation":"http://localhost:8080/git/diff/Default/file/E/a.txt",
    "New":"http://localhost:8080/file/E/a.txt",
    "Old":"http://localhost:8080/git/index/file/E/a.txt"
   }
 }

--BOUNDARY
Content-Type: plain/text

diff --git a/a.txt b/a.txt
index 380e08d..bbfd849 100644
--- a/a.txt
+++ b/a.txt
@@ -1,3 +1,4 @@
fdsfdsafdsad
asasasa2d
-Elod
+Elod
+Something

Detailed Explanation

The diff and related uris are returned as a single multi-part response. You may use query parts=uris or parts=diff to get only one part of the response.

Getting a diff location for two commits

Overview

To get a diff location for two commits. Send a POST request to the git diff location for old commit.

HTTP Method

POST

Example Request

POST /git/diff/{old revision}/file/MyProj/file.txt

{
"New" : "{new revision}" 
}  

Example Response

HTTP/1.1 200 OK
 Content-Type: text/plain
 Content-Length: 22
 Location: /git/diff/{old revision}..{new revision}/file/MyProj/file.txt

<nothing>

Detailed Explanation

TBD.

Getting a file content from index

Overview

To retrieve file content kept in index. Send a GET request to the git index location.

HTTP Method

GET

Example Request

GET /git/index/file/MyProj/file.txt

  

Example Response

HTTP/1.1 200 OK
 Content-Type: text/plain
 Content-Length: 22

This is the content from index.

Detailed Explanation

TBD.

Unstaging files

Overview

To unstage a file, reset index and/or working tree. Send a POST request to the git index location.

HTTP Method

POST

Example Request

POST /git/index/file/MyProj/file.txt

{
"Reset" : "MIXED" 
}  

Example Response

HTTP/1.1 200 OK
 Content-Type: text/plain
 Content-Length: 22

<nothing>

Detailed Explanation

TBD.

Staging files

Overview

To stage a file, add it to index. Send a PUT request to the git index location.

HTTP Method

PUT

Example Request

PUT /git/index/file/MyProj/file.txt

  

Example Response

HTTP/1.1 200 OK
 Content-Type: text/plain
 Content-Length: 22

<nothing>

Detailed Explanation

TBD.

Getting the list of remotes

Overview

To get the list of remotes send a GET request to the git remote location.

HTTP Method

POST

Example Request

POST /git/remote/file/E/

  

Example Response

HTTP/1.1 200 OK

{"Children": [{
 "Location": "http://localhost:8080/git/remote/origin/file/E/",
 "Name": "origin"
 }]}

Detailed Explanation

TBD

Getting the list of remote's branches

Overview

To get the list of remote's branches send a GET request to the git remote location.

HTTP Method

GET

Example Request

GET /git/remote/(remote)/file/E/

  

Example Response

HTTP/1.1 200 OK

{
 "Children": [{
   "CommitLocation": "http://localhost:8080/git/commit/bbbcc34fe10c2d731e7f97618f4f469c2f763a31/file/E/",
   "Id": "bbbcc34fe10c2d731e7f97618f4f469c2f763a31",
   "Location": "http://localhost:8080/git/remote/origin/master/file/E/",
   "Name": "refs/remotes/origin/master"
 }],
 "Location": "http://localhost:8080/git/remote/origin/file/E/",
 "Name": "origin"
 }

Detailed Explanation

TBD

Getting the remote branch details

Overview

To get the remote branch details send a GET request to the git remote location.

HTTP Method

GET

Example Request

GET /git/remote/(remote)/(branch)/file/E/

  

Example Response

HTTP/1.1 200 OK

{
 "CommitLocation": "http://localhost:8080/git/commit/bbbcc34fe10c2d731e7f97618f4f469c2f763a31/file/E/",
 "HeadLocation": "http://localhost:8080/git/commit/HEAD/file/E/",
 "Id": "bbbcc34fe10c2d731e7f97618f4f469c2f763a31",
 "Location": "http://localhost:8080/git/remote/origin/master/file/E/"
 }

Detailed Explanation

TBD

Adding a new remote

Overview

To add a new remote send a POST request to the git remote location.

HTTP Method

POST

Example Request

POST /git/remote/file/E/

{
 "Remote" : "{remote name}",
 "RemoteURI" : "{remote URI}",
 "FetchRefSpec" : "{fetch refspec - optional}",
 "PushURI" : "{remote push URI - optional}",
 "PushRefS[ec" : "{push refspec - optional}"
 }  

Example Response

HTTP/1.1 201 CREATED
 Location: http://localhost:8080/git/remote/newremote/file/E/
 Content-Type: application/json

{
   "Location": "http://localhost:8080/git/remote/newremote/file/E/"
 }

}

Detailed Explanation

The response contain the location of the new remote.

Fetching changes from a remote

Overview

To fetch changes from a remote send a POST request to the git branch location.

HTTP Method

POST

Example Request

POST /git/remote/(remote)/(branch)/file/E/

{
 "Fetch" : "true",
 "GitSshKnownHost" : "{git ssh known host}",
 "GitSshUsername" : "{git ssh username}",
 "GitSshPassword" : "{git ssh password}",
 "GitSshKnownHost" : "{git ssh known host}",
 "GitSshPrivateKey" : "{git ssh private key}",
 "GitSshPassphrase" : "{git ssh passphrase}"
 }  

Example Response

HTTP/1.1 201 CREATED

{
 "Id": "QEHCv6J8ABASBcDqmXX87w",
 "Location": "http://localhost:8080/task/id/QEHCv6J8ABASBcDqmXX87w",
 "Message": "Fetching origin...",
 "PercentComplete": 0,
 "Running": true
 }

Detailed Explanation

The response contain the location of the git fetch task. Call Get on the task location to check the status.

Pushing changes to a remote

Overview

To push changes from a remote send a POST request to the git branch location.

HTTP Method

POST

Example Request

POST /git/remote/(remote)/(branch)/file/E/

{
 "PushSrcRef" : "HEAD",
 "PushTags" : "true"
 "GitSshKnownHost" : "{git ssh known host}",
 "GitSshUsername" : "{git ssh username}",
 "GitSshPassword" : "{git ssh password}",
 "GitSshKnownHost" : "{git ssh known host}",
 "GitSshPrivateKey" : "{git ssh private key}",
 "GitSshPassphrase" : "{git ssh passphrase}"
 }  

Example Response

HTTP/1.1 201 CREATED

{
 "Id": "YLhATqR8ABASBcDqmXX87w",
 "Location": "http://localhost:8080/task/id/YLhATqR8ABASBcDqmXX87w",
 "Message": "Pushing origin...",
 "PercentComplete": 0,
 "Running": true
 }

Detailed Explanation

The response contain the location of the git push task. Call Get on the task location to check the status.

Removing remotes

Overview

To delete the remote send a DELETE request to the git remote location.

HTTP Method

DELETE

Example Request

DELETE /git/remote/(remote)/file/E/

  

Example Response

HTTP/1.1 200 OK

Detailed Explanation

HTTP status code 200 OK is returned, when the remote is successfully removed.

Getting status for a git project

Overview

To retrieve the working tree status of a project, send a GET request to the git status location.

HTTP Method

GET

Example Request

GET /git/status/file/A/folder/

  

Example Response

HTTP/1.1 200 OK
 Content-Type: application/json; charset=UTF-8
 Content-Length: 468

{
 "Added": [],
 "Changed": [],
 "CommitLocation": "http://localhost:8080/git/commit/HEAD/file/E/",
 "Conflicting": [],
 "IndexLocation": "http://localhost:8080/git/index/file/E/",
 "Missing": [],
 "Modified": [{
   "Git": {
     "CommitLocation": "http://localhost:8080/git/commit/HEAD/file/E/a.txt",
     "DiffLocation": "http://localhost:8080/git/diff/Default/file/E/a.txt",
     "IndexLocation": "http://localhost:8080/git/index/file/E/a.txt"
   },
   "Location": "http://localhost:8080/file/E/a.txt",
   "Name": "a.txt",
   "Path": "a.txt"
 }],
 "Removed": [],
 "Untracked": []
 }

Detailed Explanation

"IndexLocation" can be used to add all files to index, "CommitLocation" can be used to commit all files.

Tagging a commit

Overview

To tag a commit send a POST request to the git tag location.

HTTP Method

POST

Example Request

POST /git/tag/

{
 "Name" : "(tag name)",
 "Commit" : "{refId}"
 }  

Example Response

HTTP/1.1 201 CREATED
 Content-Type: text/plain
 Content-Length: 22

TBD

Detailed Explanation

TBD

Getting the list of tags

Overview

To get the list of tags send a GET request to the git tag location.

HTTP Method

GET

Example Request

GET /git/tag/file/E/

  

Example Response

HTTP/1.1 200 OK

TBD

Detailed Explanation

TBD

JSON representations

File representation extension

The JSON representation for files and directories used by file API may be extended as follows: Required fields are shown in bold. A client cannot rely on the existence of non-required attribute in a file representation from a given Orion server.

Resource/HTTP method matrix