Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

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

(Listing branches)
m (git branch)
Line 10: Line 10:
 
=== git branch ===
 
=== git branch ===
 
* [[#Listing branches]]
 
* [[#Listing branches]]
* [[#Getting branch details]]
+
* [[#Getting branch metadata]]
 
* [[#Creating a branch]]
 
* [[#Creating a branch]]
 
* [[#Removing a branch]]
 
* [[#Removing a branch]]

Revision as of 07:26, 24 June 2011

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

Git commands

git add

git branch

git checkout

git clone

git config

git commit

git diff

git fetch

git init

git log

see bug 339104

git merge

see bug 339111

git mv

see bug 349168

git pull

see bug 339114

git push

see bug 339115

git remote

see bug 339109

git reset

git revert

see bug 339105

git rm

see bug 349299

git status

#Getting status for a git project

git tag

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 /gitapi/clone/workspace/P/

  
Example Response
HTTP/1.1 200 OK

{"Children": [
 {
   "BranchLocation": "http://localhost:8080/gitapi/branch/file/u/",
   "ConfigLocation": "http://localhost:8080/gitapi/config/clone/file/u/",
   "ContentLocation": "http://localhost:8080/file/u/",
   "GitUrl": "ssh://sfranklin@git.eclipse.org/gitroot/e4/org.eclipse.orion.client.git",
   "HeadLocation": "http://localhost:8080/gitapi/commit/HEAD/file/u/",
   "Id": "u/",
   "Location": "http://localhost:8080/gitapi/clone/file/u/",
   "Name": "sfranklin",
   "RemoteLocation": "http://localhost:8080/gitapi/remote/file/u/"
 },
 {
   "BranchLocation": "http://localhost:8080/gitapi/branch/file/q0/",
   "ConfigLocation": "http://localhost:8080/gitapi/config/clone/file/q0/",
   "ContentLocation": "http://localhost:8080/file/q0/",
   "HeadLocation": "http://localhost:8080/gitapi/commit/HEAD/file/q0/",
   "Id": "q0/",
   "Location": "http://localhost:8080/gitapi/clone/file/q0/",
   "Name": "bug349480",
   "RemoteLocation": "http://localhost:8080/gitapi/remote/file/q0/"
 }
 ]}
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 /gitapi/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.


Creating a new tag

Overview
To tag a commit send a POST request to the git tag location.
HTTP Method
POST
Example Request
POST /gitapi/tag/

{
 "Name" : "(tag name)",
 "Commit" : "{refId to tag}"
 }  
Example Response
HTTP/1.1 201 CREATED
 Content-Type: text/plain
 Content-Length: 22

TBD
Detailed Explanation
TBD


Listing tags

Overview
To get the list of tags send a GET request to the git tag location.
HTTP Method
GET
Example Request
GET /gitapi/tag/file/E/

  
Example Response
HTTP/1.1 200 OK

{
 "Children": [
   { 
     "FullName": "refs/tags/v20110606",
     "Name": "v20110606"
   },
   { 
     "FullName": "refs/tags/v20110607",
     "Name": "v20110607"
   },
   { 
     "FullName": "refs/tags/R0_2M4",
     "Name": "vR0_2M4"
   }
 ]}
Detailed Explanation
The response contains list of all tags for the given repository.


Listing branches

Overview
To get the list of branches send a GET request to the git tag location.
HTTP Method
GET
Example Request
GET /gitapi/branch/file/E/

  
Example Response
HTTP/1.1 200 OK

{
 "Children": [ 
   {
     "CloneLocation": "http://localhost:8080/gitapi/clone/file/dg/",
     "CommitLocation": "http://localhost:8080/gitapi/commit/master/file/dg/",
     "Current": true,
     "HeadLocation": "http://localhost:8080/gitapi/commit/HEAD/file/dg/",
     "Location": "http://localhost:8080/gitapi/branch/master/file/dg/",
     "Name": "master",
     "RemoteLocation": "http://localhost:8080/gitapi/remote/origin/master/file/dg/",
     "Type": "Branch"
   },
   {
     "CloneLocation": "http://localhost:8080/gitapi/clone/file/dg/",
     "CommitLocation": "http://localhost:8080/gitapi/commit/dev/file/dg/",
     "Current": false,
     "HeadLocation": "http://localhost:8080/gitapi/commit/HEAD/file/dg/",
     "Location": "http://localhost:8080/gitapi/branch/dev/file/dg/",
     "Name": "dev",
     "RemoteLocation": "http://localhost:8080/gitapi/remote/origin/dev/file/dg/",
     "Type": "Branch"
   }
 ]}
Detailed Explanation
The response contains list of all local branches for the current repository. An active branch will have "Current" property set to true.


Getting branch metadata

Overview
To get more info about a branch send a GET request to its git branch location.
HTTP Method
GET
Example Request
GET /gitapi/branch/master/file/E/

  
Example Response
HTTP/1.1 200 OK

{
   "CloneLocation": "http://localhost:8080/gitapi/clone/file/dg/",
   "CommitLocation": "http://localhost:8080/gitapi/commit/master/file/dg/",
   "Current": true,
   "HeadLocation": "http://localhost:8080/gitapi/commit/HEAD/file/dg/",
   "Location": "http://localhost:8080/gitapi/branch/master/file/dg/",
   "Name": "master",
   "RemoteLocation": "http://localhost:8080/gitapi/remote/origin/master/file/dg/",
   "Type": "Branch"
 }
Detailed Explanation
The response contains details of the selected local branch.


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.

Field Data type Value
Git.CommitLocation URI Location of Git Commit resource (HEAD)
Git.DefaultRemotebranchLocation URI Location of the default remote branch
Git.DiffLocation URI Location of Git Diff resource
Git.IndexLocation URI Location of Git Index resource
Git.RemoteLocation URI Location of Git Remote resource
Git.StatusLocation URI Location of Git Status resource
Git.TagLocation URI Location of Git Tag resource

Resource/HTTP method matrix

GET PUT POST DELETE
commit #git log #git tag #git commit, #git merge (#git pull) #git rm
index #Getting a file content from index #git add #git reset
clone #Getting the list of repositories, clone info #git checkout #git clone delete clone
config #git config #git config #git config #git config
branch #git branch #git branch #git branch #git branch
tag #git tag #git tag #git tag #git tag
remote #git remote #git remote, #git fetch, #git push #git remote
diff #git diff #Getting a diff location for two commits
status #git status

Back to the top