Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Orion/Server API/Git API

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

Contents

Resource/HTTP method matrix

GET PUT POST DELETE
blame #Getting blame result from HEAD
#Getting blame result from commit
branch #Listing branches
#Getting branch metadata 		#Creating a branch #Removing a branch
clone #Getting the list of repositories #Checking out a branch
#Discarding changes in working directory 		#Creating a repository clone
#Initializing a git repository 		#Removing a clone
commit #Listing commits
#Listing commits revision or named commits
#Getting commit metadata
#Getting file content in a commit
#Getting a file content from HEAD
#Getting file content in a commit 		#Tagging a commit #Committing all files in index
#Amending a commit
#Committing a single file
#Merging changes from a remote to HEAD
#Cherry-picking a commit 		#git rm
config #Getting repository options
#Getting repository option 		#Updating repository option #Setting repository option #Unsetting repository option
diff #Getting a diff between working tree and index
#Getting a diff between index and HEAD
#Getting a diff between two commits 		#Getting a diff location for two commits
index #Getting a file content from index #Staging a file
#Staging files 		#Unstaging all files in the index
#Unstaging a single file
#Unstaging a group of files
remote #Getting the list of remotes
#Getting the list of remote's branches
#Getting the remote branch details 		#Adding a new remote
#Fetching changes from a remote
#Pushing changes to a remote 		#Removing remotes
status #Getting status for a git project
tag #Listing tags #Creating a new tag #Removing a tag

Git commands

git add

git blame

git branch

git checkout

git cherry-pick

git clone

git config

git commit

git diff

git fetch

git init

git log

git merge

git mv

see bug 349168

git pull

see bug 339114

git push

git remote

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/{:workspace_id}/
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/",
   "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/",
   "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 /gitapi/clone/

{
 "Location" : "/workspace/{workspace_id}",
 "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 /gitapi/clone/

{
 "Name" : "{repo_name}",
 "Location" : "/workspace/{workspace_id}",
 "GitMail" : "{committer e-mail address}",
 "GitName" : "{committer name}"
 }
Example Response
HTTP/1.1 201 CREATED

{
 "Location": "http://localhost:8080/git/clone/file/user-OrionContent/repo"
 }
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).


Removing a clone

Overview
To delete a clone send a DELETE request to the git clone location.
HTTP Method
DELETE
Example Request
DELETE /gitapi/clone/file/{:workspace_id}/{:repo_dir}/
Example Response
HTTP/1.1 200 OK
Detailed Explanation
No response. The clone and its folder have been deleted.


Getting repository options

Overview
To get the list of repository options send a GET request to the git config location.
HTTP Method
GET
Example Request
GET /gitapi/config/clone/file/{:workspace_id}/{:repo_dir}/
Example Response
HTTP/1.1 200 OK

{"Children": [
 {
   "Key": "core.repositoryformatversion",
   "Location": "http://localhost:8080/gitapi/config/core.repositoryformatversion/clone/file/A/",
   "Value": ["0"]
 },
 {
   "Key": "core.filemode",
   "Location": "http://localhost:8080/gitapi/config/core.filemode/clone/file/A/",
   "Value": ["false"]
 },
 {
   "Key": "core.logallrefupdates",
   "Location": "http://localhost:8080/gitapi/config/core.logallrefupdates/clone/file/A/",
   "Value": ["true"]
 },
 {
   "Key": "core.autocrlf",
   "Location": "http://localhost:8080/gitapi/config/core.autocrlf/clone/file/A/",
   "Value": ["false"]
 },
 {
   "Key": "user.name",
   "Location": "http://localhost:8080/gitapi/config/user.name/clone/file/A/",
   "Value": ["John"]
 },
 {
   "Key": "user.email",
   "Location": "http://localhost:8080/gitapi/config/user.email/clone/file/A/",
   "Value": ["john@email.com"]
 }
 ]}
Detailed Explanation
The response contains the list of all repository options. Each option contains its location, which can be used for update or delete operation.


Getting repository option

Overview
To get the repository option send a GET request to the git config option location.
HTTP Method
GET
Example Request
GET /gitapi/config/user.name/clone/file/{:workspace_id}/{:repo_dir}/
Example Response
HTTP/1.1 200 OK

{
   "Key": "user.name",
   "Location": "http://localhost:8080/gitapi/config/user.name/clone/file/user-OrionContent/repo/",
   "Value": ["John"]
 }
Detailed Explanation
The response contains the repository option key, value and location.


Updating repository option

Overview
To update repository option send a PUT request to the git config option location. POST also can be used, see #Setting repository option.
HTTP Method
PUT
Example Request
PUT /gitapi/config/user.name/clone/file/{:workspace_id}/{:repo_dir}/

{
 "Value" : "John"
 }
Example Response
HTTP/1.1 200 OK

{
   "Key": "user.name",
   "Location": "http://localhost:8080/gitapi/config/user.name/clone/file/user-OrionContent/repo/",
   "Value": ["John"]
 }
Detailed Explanation
The response contains the repository option key, value and location.


Setting repository option

Overview
To set a new repository option send a POST request to the git config location.
HTTP Method
POST
Example Request
POST /gitapi/config/clone/file/{:workspace_id}/{:repo_dir}/

{
 "Key" : "user.name",
 "Value" : "Alice"
 }
Example Response
HTTP/1.1 201 CREATED

{
   "Key": "user.name",
   "Location": "http://localhost:8080/gitapi/config/user.name/clone/file/user-OrionContent/repo/",
   "Value": ["Alice"]
 }
Detailed Explanation
The response contains the repository option key, value and location.


Unsetting repository option

Overview
To unset repository option send a DELETE request to the git config option location.
HTTP Method
DELETE
Example Request
DELETE /gitapi/config/user.name/clone/file/{:workspace_id}/{:repo_dir}/
Example Response
HTTP/1.1 200 OK
Detailed Explanation
No response. The repository option has been unset.


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 /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/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 /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/

{
"Message" : "fixing bug 349827" 
}
Example Response
HTTP/1.1 200 OK

{
 "AuthorEmail": "Tomasz.Zarna@pl.ibm.com",
 "AuthorName": "Tomasz Zarna",
 "Children": [],
 "CommitterEmail": "Tomasz.Zarna@pl.ibm.com",
 "CommitterName": "Tomasz Zarna",
 "ContentLocation": "http://localhost:8080/gitapi/commit/1fe0d121457ec1fc61d86e497576972443cdb14a/file/user-OrionContent/repo/?parts=body",
 "DiffLocation": "http://localhost:8080/gitapi/diff/1fe0d121457ec1fc61d86e497576972443cdb14a/file/user-OrionContent/repo/",
 "Diffs": [{
   "ChangeType": "MODIFY",
   "DiffLocation": "http://localhost:8080/gitapi/diff/c47c36518cd8aaf01b84afa55cf9a75badc882d9..1fe0d121457ec1fc61d86e497576972443cdb14a/file/user-OrionContent/repo/folder/file.txt",
   "NewPath": "folder/file.txt",
   "OldPath": "folder/file.txt",
   "Type": "Diff"
 }],
 "Location": "http://localhost:8080/gitapi/commit/1fe0d121457ec1fc61d86e497576972443cdb14a/file/user-OrionContent/repo/",
 "Message": "fixing bug 349827",
 "Name": "1fe0d121457ec1fc61d86e497576972443cdb14a",
 "Time": 1308917875000,
 "Type": "Commit"

}

Detailed Explanation
The response will contain a newly created commit.


Amending a commit

Overview
To amend the last commit. Send a POST request to the git commit location.
HTTP Method
POST
Example Request
POST /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/

{
"Message" : "{amended commit message}",
"Amend" : "true",
"ChangeId" : false,
"AuthorName" : "{author name}",
"AuthorEmail" : "{author email}",
"CommitterName" : "{committer name}",
"CommitterEmail" : "{committer email}",
"persist" : false
}
Example Response
HTTP/1.1 200 OK

see #Committing all files in index
Detailed Explanation
TBD.


Committing a single file

Overview
To commit a single. Send a POST request to the git commit location of that file.
HTTP Method
POST
Example Request
POST /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/{:file_path}

{
"Message" : "fixing bug 349827" 
}
Example Response
HTTP/1.1 200 OK

{
 "AuthorEmail": "Tomasz.Zarna@pl.ibm.com",
 "AuthorName": "Tomasz Zarna",
 "Children": [],
 "CommitterEmail": "Tomasz.Zarna@pl.ibm.com",
 "CommitterName": "Tomasz Zarna",
 "ContentLocation": "http://localhost:8080/gitapi/commit/91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9/file/user-OrionContent/repo/test.txt?parts=body",
 "DiffLocation": "http://localhost:8080/gitapi/diff/91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9/file/user-OrionContent/repo/test.txt",
 "Diffs": [{
   "ChangeType": "MODIFY",
   "DiffLocation": "http://localhost:8080/gitapi/diff/1fe0d121457ec1fc61d86e497576972443cdb14a..91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9/file/user-OrionContent/repo/test.txt",
   "NewPath": "test.txt",
   "OldPath": "test.txt",
   "Type": "Diff"
 }],
 "Location": "http://localhost:8080/gitapi/commit/91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9/file/user-OrionContent/repo/test.txt",
 "Message": "fixing bug 349827",
 "Name": "91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9",
 "Time": 1308918640000,
 "Type": "Commit"

}

Detailed Explanation
Like when #Committing all files in index the response will contain a newly created commit. The difference is that it's not required the file has been staged.


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 /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/

{
 "Merge" : "{refId}"
 }
Example Response
HTTP/1.1 200 OK

{"Result": "ALREADY_UP_TO_DATE"}
Detailed Explanation
TBD.


Cherry-picking a commit

Overview
To cherry-pick a commit send a POST request to the git commit location.
HTTP Method
POST
Example Request
POST /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/

{
 "Cherry-Pick" : "e345e82f3e793be3ce872f5784da92f4a9e50007"
 }
Example Response
HTTP/1.1 200 OK

{"Result": "OK", "HeadUpdated" : "true"}
Detailed Explanation
When cherry-picking succeeded "OK" is returned. Other possible results are "FAILED" and "CONFLICTING". "HeadUpdated" parameter informs whether HEAD has moved. If trying to cherry-pick a commit which has been already picked, the result will say "OK", but the second param will indicate that nothing has actually changed.


Tagging a commit

Overview
To tag a commit send a PUT request to the git commit location.
HTTP Method
PUT
Example Request
PUT /gitapi/commit/(revision)/file/{:workspace_id}/{:repo_dir}/

{
 "Name" : "{tag name}" 
 "Annotated" : "{true or false}" 
 "Message" : "{annotated tag message}" 
 }
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/user-OrionContent/repo/?parts=body",
 "DiffLocation": "http://localhost:8080/git/diff/(revision)/file/user-OrionContent/repo/",
 "Location": "http://localhost:8080/git/commit/(revision)/file/user-OrionContent/repo/",
 "Message": "(commit message)",
 "Name": "(commit name)",
 "Time": 1304073355000
 }
Detailed Explanation
TBD.


Removing a tag

Overview
To deleta a tag a DELETE request to the git tag location.
HTTP Method
DELETE
Example Request
DELETE /gitapi/tag/tag1/file/{:workspace_id}/{:repo_dir}/
Example Response
HTTP/1.1 200 OK
Detailed Explanation
No response. The tag has been removed.


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 /gitapi/diff/Default/file/{:workspace_id}/{:repo_dir}/
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

{
  "Base":"http://localhost:8080/git/index/file/repo/a.txt",
  "Location":"http://localhost:8080/git/diff/Default/file/repo/a.txt",
  "New":"http://localhost:8080/file/repo/a.txt",
  "Old":"http://localhost:8080/git/index/file/repo/a.txt",
  "Type":"Diff"
 }

--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 /gitapi/diff/Cached/file/{:workspace_id}/{:repo_dir}/
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

{
  "Base":"http://localhost:8080/git/index/file/repo/a.txt",
  "Diff":"http://localhost:8080/git/diff/Default/file/repo/a.txt",
  "New":"http://localhost:8080/file/repo/a.txt",
  "Old":"http://localhost:8080/git/index/file/repo/a.txt",
  "Type":"Diff"
 }

--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 /gitapi/diff/{:old revision}..{:new revision}/file/{:workspace_id}/{:repo_dir}/?parts={:diffs/uris}&pageSize={:page_size}&page={:page_number}
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

{
  "Base":"http://localhost:8080/git/index/file/repo/a.txt",
  "Location":"http://localhost:8080/git/diff/Default/file/repo/a.txt",
  "New":"http://localhost:8080/file/repo/a.txt",
  "Old":"http://localhost:8080/git/index/file/repo/a.txt",
  "Type":"Diff"
 }

--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
If query parameter "parts=diffs" then "pageSize" and "page" must also be specified.


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 /gitapi/diff/{:old revision}/file/{:workspace_id}/{:repo_dir}/{:file_path}

{
"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/repo/

<nothing>
Detailed Explanation
TBD.


Getting 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 /gitapi/index/file/{:workspace_id}/{:repo_dir}/{:file_path}
Example Response
HTTP/1.1 200 OK
 Content-Type: text/plain
 Content-Length: 22

This is the content from index.
Detailed Explanation
TBD.


Unstage all files in the index

Overview
To unstage all previously-staged files, reset index and/or working tree. Send a POST request to the git index location.
HTTP Method
POST
Example Request
POST /gitapi/index/file/{:workspace_id}/{:repo_dir}/

{
"Reset" : "MIXED" 
}
Example Response
HTTP/1.1 200 OK
Detailed Explanation
No response body. Subsequent request for git status will show that all staged files are now unstaged.


Unstaging a group of files

Overview
To unstage a group of files. Send a POST request to the git index location.
HTTP Method
POST
Example Request
POST /gitapi/index/file/{:workspace_id}/{:repo_dir}/

{
"Path" : ["folder/file.txt", "file1.txt" ]
}
Example Response
HTTP/1.1 200 OK
Detailed Explanation
No response body. Subsequent request for git status will show that the files have been unstaged.


Unstaging a single file

Overview
To unstage an individual file. Send a POST request to the git index location.
HTTP Method
POST
Example Request
POST /gitapi/index/file/{:workspace_id}/{:repo_dir}/file.txt
Example Response
HTTP/1.1 200 OK
Detailed Explanation
No response body. Subsequent request for git status will show that the file has been unstaged.


Staging a file

Overview
To stage a file, add it to the index. Send a PUT request to the git index location.
HTTP Method
PUT
Example Request
PUT /gitapi/index/file/{:workspace_id}/{:repo_dir}/{:file_path}
Example Response
HTTP/1.1 200 OK
Detailed Explanation
No response body, see #Getting status for a git project to verify the file has been added to index.


Staging files

Overview
To stage multiple files, add them to the index. Send a PUT request to the git index location.
HTTP Method
PUT
Example Request
PUT /gitapi/index/file/{:workspace_id}/{:repo_dir}/

{
 "Path" : ["file1.txt", "folder/file.txt"] 
 }
Example Response
HTTP/1.1 200 OK
Detailed Explanation
No response body, see #Getting status for a git project to verify all files have been added to index.


Getting the list of remotes

Overview
To get the list of remotes send a GET request to the git remote location.
HTTP Method
GET
Example Request
GET /gitapi/remote/file/{:workspace_id}/{:repo_dir}/
Example Response
HTTP/1.1 200 OK

{
 "Children": [
   {
     "CloneLocation": "/gitapi/clone/file/user-OrionContent/repo/orion.client/",
     "GitUrl": "https://github.com/user/orion.client.git",
     "IsGerrit": false,
     "Location": "/gitapi/remote/origin/file/user-OrionContent/repo/orion.client/",
     "Name": "origin",
     "Type": "Remote"
   },
   {
     "CloneLocation": "/gitapi/clone/file/user-OrionContent/repo/orion.client/",
     "GitUrl": "http://git.eclipse.org/gitroot/orion/org.eclipse.orion.client.git",
     "IsGerrit": false,
     "Location": "/gitapi/remote/upstream/file/user-OrionContent/repo/orion.client/",
     "Name": "upstream",
     "Type": "Remote"
   }
 ],
 "Type": "Remote"

}

Detailed Explanation
TBD


Getting the list of a remote's branches

Overview
To get the list of a remote's branches send a GET request to the git remote location.
HTTP Method
GET
Example Request
GET /gitapi/remote/{:remote}/file/{:workspace_id}/{:repo_dir}/
Example Response
HTTP/1.1 200 OK

{
 "Children": [{
   "CommitLocation": "http://localhost:8080/git/commit/bbbcc34fe10c2d731e7f97618f4f469c2f763a31/file/repo/",
   "Id": "bbbcc34fe10c2d731e7f97618f4f469c2f763a31",
   "Location": "http://localhost:8080/git/remote/origin/master/file/repo/",
   "Name": "refs/remotes/origin/master"
 }],
 "Location": "http://localhost:8080/git/remote/origin/file/repo/",
 "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 /gitapi/remote/{:remote}/{:branch}/file/{:workspace_id}/{:repo_dir}/
Example Response
HTTP/1.1 200 OK

{
 "CommitLocation": "http://localhost:8080/git/commit/bbbcc34fe10c2d731e7f97618f4f469c2f763a31/file/repo/",
 "HeadLocation": "http://localhost:8080/git/commit/HEAD/file/repo/",
 "Id": "bbbcc34fe10c2d731e7f97618f4f469c2f763a31",
 "Location": "http://localhost:8080/git/remote/origin/master/file/repo/"
 }
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 /gitapi/remote/file/{:workspace_id}/{:repo_dir}/

{
 "Remote" : "{remote name}",
 "RemoteURI" : "{remote URI}",
 "FetchRefSpec" : "{fetch refspec - optional}",
 "PushURI" : "{remote push URI - optional}",
 "PushRefSpec" : "{push refspec - optional}"
 }
Example Response
HTTP/1.1 201 CREATED
 Location: http://localhost:8080/git/remote/newremote/file/repo/
 Content-Type: application/json

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

}

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 /gitapi/remote/{:remote}/{:branch}/file/{:workspace_id}/{:repo_dir}/

{
 "Fetch" : "true",
 "GitSshKnownHost" : "{git ssh known host}",
 "GitSshUsername" : "{git ssh username}",
 "GitSshPassword" : "{git ssh password}",
 "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 /gitapi/remote/{:remote}/{:branch}/file/{:workspace_id}/{:repo_dir}/

{
 "PushSrcRef" : "HEAD",
 "PushTags" : "true",
 "Force" : "false",
 "GitSshKnownHost" : "{git ssh known host}",
 "GitSshUsername" : "{git ssh username}",
 "GitSshPassword" : "{git ssh password}",
 "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 /gitapi/remote/{:remote}/file/{:workspace_id}/{:repo_dir}/
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/{:workspace_id}/{:repo_dir}/
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/repo/",
 "Conflicting": [],
 "IndexLocation": "http://localhost:8080/git/index/file/repo/",
 "Missing": [],
 "Modified": [{
   "Git": {
     "CommitLocation": "http://localhost:8080/git/commit/HEAD/file/repo/a.txt",
     "DiffLocation": "http://localhost:8080/git/diff/Default/file/repo/a.txt",
     "IndexLocation": "http://localhost:8080/git/index/file/repo/a.txt"
   },
   "Location": "http://localhost:8080/file/repo/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 PUT request to the git tag location.
HTTP Method
PUT
Example Request
PUT /gitapi/commit/{:refId}/file/{:workspace_id}/{:repo_dir}

{
 "Name" : "{tag name}",
 "Annotated" : boolean,
 "Message" : "{annotated message}",
 }
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/{:workspace_id}/{:repo_dir}/
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/{:workspace_id}/{:repo_dir}/
Example Response
HTTP/1.1 200 OK

{
 "Children": [ 
   {
     "CloneLocation": "http://localhost:8080/gitapi/clone/file/repo/",
     "CommitLocation": "http://localhost:8080/gitapi/commit/master/file/repo/",
     "Current": true,
     "HeadLocation": "http://localhost:8080/gitapi/commit/HEAD/file/repo/",
     "Location": "http://localhost:8080/gitapi/branch/master/file/repo/",
     "Name": "master",
     "RemoteLocation": "http://localhost:8080/gitapi/remote/origin/master/file/repo/",
     "Type": "Branch"
   },
   {
     "CloneLocation": "http://localhost:8080/gitapi/clone/file/repo/",
     "CommitLocation": "http://localhost:8080/gitapi/commit/dev/file/repo/",
     "Current": false,
     "HeadLocation": "http://localhost:8080/gitapi/commit/HEAD/file/repo/",
     "Location": "http://localhost:8080/gitapi/branch/dev/file/repo/",
     "Name": "dev",
     "RemoteLocation": "http://localhost:8080/gitapi/remote/origin/dev/file/repo/",
     "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/{:workspace_id}/{:repo_dir}/
Example Response
HTTP/1.1 200 OK

{
   "CloneLocation": "http://localhost:8080/gitapi/clone/file/repo/",
   "CommitLocation": "http://localhost:8080/gitapi/commit/master/file/repo/",
   "Current": true,
   "DiffLocation": "http://localhost:8080/gitapi/diff/master/file/repo/",
   "FullName": "refs/heads/master",
   "HeadLocation": "http://localhost:8080/gitapi/commit/HEAD/file/repo/",
   "LocalTimeStamp": 1234567890000,
   "Location": "http://localhost:8080/gitapi/branch/master/file/repo/",
   "Name": "master",
   "RemoteLocation": ["http://localhost:8080/gitapi/remote/origin/master/file/repo/"],
   "TreeLocation": "http://localhost:8080/gitapi/tree/file/repo/master",
   "Type": "Branch"
 }
Detailed Explanation
The response contains details of the selected local branch.


Creating a branch

Overview
To create a local send a POST request to the git BranchLocation. The data must be JSON.
HTTP Method
POST
Example Request
POST /gitapi/branch/file/{:workspace_id}/{:repo_dir}/

{
 "Name" : "dev",
 "Branch" : "{starting point}" (if omitted the current HEAD will be used)
 }
Example Response
HTTP/1.1 201 CREATED

{
 "CloneLocation": "http://localhost:8080/gitapi/clone/file/repo/",
 "CommitLocation": "http://localhost:8080/gitapi/commit/dev/file/repo/",
 "Current": false,
 "HeadLocation": "http://localhost:8080/gitapi/commit/HEAD/file/repo/",
 "Location": "http://localhost:8080/gitapi/branch/dev/file/repo/",
 "Name": "dev",
 "RemoteLocation": "http://localhost:8080/gitapi/remote/origin/dev/file/repo/",
 "Type": "Branch"
 }
Detailed Explanation
The response contain the newly created branch. Note this is not an active branch yet. You need to check it out first, see #Checking out a branch.


Removing a branch

Overview
To remove a local branch send a DELETE request to its git branch location.
HTTP Method
DELETE
Example Request
DELETE /gitapi/branch/master/file/{:workspace_id}/{:repo_dir}/
Example Response
HTTP/1.1 200 OK
Detailed Explanation
The response is empty. Subsequent calls on the branch location will return 404 NOT FOUND.


Checking out a branch

Overview
To checkout a branch send a PUT request to the git clone Location. The data must be JSON.
HTTP Method
PUT
Example Request
PUT /gitapi/clone/file/{:workspace_id}/{:repo_dir}/

{
 "Branch" : "dev" 
 }
Example Response
HTTP/1.1 200 OK
Detailed Explanation
No response body, but subsequent requests for branch details will indicate that 'dev' is now an active (current) branch.


Checking out a tag

Overview
To checkout a tag send a PUT request to the git clone location. A new branch will be created for the requested tag.
HTTP Method
PUT
Example Request
PUT /gitapi/clone/file/{:workspace_id}/{:repo_dir}/

{
 "Tag" : "stable"
 "Branch" : "tag_stable" 
 }
Example Response
HTTP/1.1 200 OK
Detailed Explanation
No response body, but subsequent requests for branch details will indicate that 'tag_stable' is now an active (current) branch. Until http://egit.eclipse.org/r/#change,4336 is resolved, the branch name should be different than the tag.


Discarding changes in working directory

Overview
To checkout a file send a PUT request to the git clone location.
HTTP Method
PUT
Example Request
PUT /gitapi/clone/file/{:workspace_id}/{:repo_dir}/

{
 "Path" : ["folder/file.txt"]
 }
Example Response
HTTP/1.1 200 OK
Detailed Explanation
No response body, but subsequent request for the file content will show that its content has been replaced with the index.


Listing commits

Overview
To get list of commits (log) send a GET request to the HeadLocation.
HTTP Method
GET
Example Request
GET /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/?parts=log
Example Response
HTTP/1.1 200 OK

{
 "Children": [
   {
     "AuthorEmail": "Tomasz.Zarna@pl.ibm.com",
     "AuthorName": "Tomasz Zarna",
     "Children": [],
     "CommitterEmail": "Tomasz.Zarna@pl.ibm.com",
     "CommitterName": "Tomasz Zarna",
     "ContentLocation": "http://localhost:8080/gitapi/commit/91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9/file/repo/?parts=body",
     "DiffLocation": "http://localhost:8080/gitapi/diff/91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9/file/repo/",
     "Diffs": [{
       "ChangeType": "MODIFY",
       "DiffLocation": "http://localhost:8080/gitapi/diff/1fe0d121457ec1fc61d86e497576972443cdb14a..91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9/file/repo/test.txt",
       "NewPath": "test.txt",
       "OldPath": "test.txt",
       "Type": "Diff"
     }],
     "Location": "http://localhost:8080/gitapi/commit/91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9/file/repo/",
     "Message": "fixing bug 349827",
     "Name": "91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9",
     "Time": 1308918640000,
     "Type": "Commit"
   }
 ],
 "RepositoryPath": "",
 "toRef": {
   "CloneLocation": "http://localhost:8080/gitapi/clone/file/repo/",
   "CommitLocation": "http://localhost:8080/gitapi/commit/master/file/repo/",
   "Current": true,
   "HeadLocation": "http://localhost:8080/gitapi/commit/HEAD/file/repo/",
   "Location": "http://localhost:8080/gitapi/branch/master/file/repo/",
   "Name": "master",
   "Type": "Branch"
 }

}

Detailed Explanation
The response contains list of commits (see response for #Committing all files in index) and details about refs used in the log when available.

There is also an alternative API where (I guess ?parts=log is replaced by) ?page=page_no&pageSize=page_size. In the response you'll get NextLocation and PreviousLocation that will direct you to the next and previous page.


Listing commits revision or named commits

Overview
To get list of commits (log) using a revision. If revision is "master..myBranch", the response will be the commits on myBranch since it was branched from master. If revision is "master~4..master", the response will be the 4 most recent commits on master; if there are less than 4, the result will be status 400 error.
HTTP Method
GET
Example Request
GET /gitapi/commit/master~4..master/file/{:workspace_id}/{:repo_dir}
Example Response
HTTP/1.1 200 OK

{
 "Children": [
   {
     "AuthorEmail": "Tomasz.Zarna@pl.ibm.com",
     "AuthorName": "Tomasz Zarna",
     "Children": [],
     "CommitterEmail": "Tomasz.Zarna@pl.ibm.com",
     "CommitterName": "Tomasz Zarna",
     "ContentLocation": "http://localhost:8080/gitapi/commit/91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9/file/repo/?parts=body",
     "DiffLocation": "http://localhost:8080/gitapi/diff/91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9/file/repo/",
     "Diffs": [{
       "ChangeType": "MODIFY",
       "DiffLocation": "http://localhost:8080/gitapi/diff/1fe0d121457ec1fc61d86e497576972443cdb14a..91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9/file/repo/test.txt",
       "NewPath": "test.txt",
       "OldPath": "test.txt",
       "Type": "Diff"
     }],
     "Location": "http://localhost:8080/gitapi/commit/91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9/file/repo/",
     "Message": "fixing bug 349827",
     "Name": "91e0cd59fcf0be00fb9d2469e4eb06e7620e97c9",
     "Time": 1308918640000,
     "Type": "Commit"
   }
 ],
 "RepositoryPath": "",
 "toRef": {
   "CloneLocation": "http://localhost:8080/gitapi/clone/file/repo/",
   "CommitLocation": "http://localhost:8080/gitapi/commit/master/file/repo/",
   "Current": true,
   "HeadLocation": "http://localhost:8080/gitapi/commit/HEAD/file/repo/",
   "Location": "http://localhost:8080/gitapi/branch/master/file/repo/",
   "Name": "master",
   "Type": "Branch"
 }

}

Detailed Explanation
The response contains an array of commits on the Children property.


Getting commit metadata

Overview
To get details of a commit send a GET request to git commit location.
HTTP Method
GET
Example Request
GET /gitapi/commit/c47c36518cd8aaf01b84afa55cf9a75badc882d9/file/{:workspace_id}/{:repo_dir}/{:file_path}
Example Response
HTTP/1.1 200 OK

{
 "Children": [{
   "AuthorEmail": "Tomasz.Zarna@pl.ibm.com",
   "AuthorName": "Tomasz Zarna",
   "Children": [],
   "CommitterEmail": "Tomasz.Zarna@pl.ibm.com",
   "CommitterName": "Tomasz Zarna",
   "ContentLocation": "http://localhost:8080/gitapi/commit/c47c36518cd8aaf01b84afa55cf9a75badc882d9/file/filepath/?parts=body",
   "DiffLocation": "http://localhost:8080/gitapi/diff/c47c36518cd8aaf01b84afa55cf9a75badc882d9/file/filepath/",
   "Location": "http://localhost:8080/gitapi/commit/c47c36518cd8aaf01b84afa55cf9a75badc882d9/file/filepath/",
   "Message": "initial commit\n",
   "Name": "c47c36518cd8aaf01b84afa55cf9a75badc882d9",
   "Time": 1308667721000,
   "Type": "Commit"
 }],
 "RepositoryPath": ""

}

Detailed Explanation
The response contains details for the selected commit.


Getting file content in a commit

Overview
To retrieve file content kept for a specific commit. Send a GET request to the git commit location.
HTTP Method
GET
Example Request
GET /gitapi/commit/c47c36518cd8aaf01b84afa55cf9a75badc882d9/file/{:workspace_id}/{:repo_dir}/{:file_path}?parts=body
Example Response
HTTP/1.1 200 OK

I'm content of file.txt
Detailed Explanation
The response contains content of the selected file in the given commit.


Getting blame result from HEAD

Overview
Retrieve blame information for the specified file from HEAD.
HTTP Method
GET
Example Request
GET /gitapi/blame/HEAD/file/{:workspace_id}/{:repo_dir}/{:file_path}
Example Response
HTTP/1.1 200 OK

{
 "Children": [
   {
     "AuthorEmail": "author@email.com ",
     "AuthorImage": "http://www.gravatar.com/avatar/677bc1ca5ef557ab8f9c94038c0312b7?d=mm",
     "AuthorName": "Author Name",
     "CommitLocation": "/gitapi/commit/4065d87b7a839f41d9be40ca11b7ad2f78784bcc/file/location/",
     "Message": "commit message",
     "Name": "4065d87b7a839f41d9be40ca11b7ad2f78784bcc",
     "Time": 1367897569,
     "Children": [
     	{
         "Start": "1",
         "End": "4"
       },
       {
         "Start": "7",
         "End": "8"
       },
      ...
     ]
   },
   ...
 ],
 "CloneLocation": "/gitapi/clone/file/location/",
 "Location": "/gitapi/blame/HEAD/file/Name/location/file.js",
 "Type": "Blame"
}
Detailed Explanation
The response contains all of the information needed to generate blame for the current file. Each commit that appears in the file's blame information resides in the responses' children. For each commit the author's name, email and Gravatar image link are included, along with the commit's location, message, name and time. Each commit also contains an array of line ranges which are blamed to this commit.


Getting blame result from commit

Overview
Retrieve blame information for the specified file for a commit.
HTTP Method
GET
Example Request
GET /gitapi/blame/{:sha}/file/{:workspace_id}/{:repo_dir}/{:file_path}
Example Response
HTTP/1.1 200 OK

{
 "Children": [
   {
     "AuthorEmail": "author@email.com ",
     "AuthorImage": "http://www.gravatar.com/avatar/677bc1ca5ef557ab8f9c94038c0312b7?d=mm",
     "AuthorName": "Author Name",
     "CommitLocation": "/gitapi/commit/af15c87b26c75263c005db59fb1513190b05c3f1/file/location/",
     "Message": "commit message",
     "Name": "af15c87b26c75263c005db59fb1513190b05c3f1",
     "Time": 1367894569,
     "Children": [
     {
         "Start": "1",
         "End": "3"
       },
       {
         "Start": "7",
         "End": "8"
       },
      ...
     ]
   },
   ...
 ],
 "CloneLocation": "/gitapi/clone/file/location/",
 "Location": "/gitapi/blame/HEAD/file/Name/location/file.js",
 "Type": "Blame"
}
Detailed Explanation
The response contains the blame information for a file for a certain commit. See #Getting blame result from HEAD


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
Retrieved from "http://wiki.eclipse.org/index.php?title=Orion/Server_API/Git_API&oldid=421370"

This page was last modified 12:10, 20 December 2017 by Eclipsepedia anonymous user Unnamed Poltroon.

Back to the top