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"

m (REST API)
m (Adding a new remote)
 
(358 intermediate revisions by 10 users not shown)
Line 1: Line 1:
 
The Git API is a web server API for browsing and manipulating Git repositories.
 
The Git API is a web server API for browsing and manipulating Git repositories.
 +
 +
== Resource/HTTP method matrix ==
 +
 +
{| class="wikitable" style="width:100%" border="1"
 +
|-
 +
!
 +
!width="25%"|GET
 +
!width="25%"|PUT
 +
!width="25%"|POST
 +
!width="25%"|DELETE
 +
|-
 +
! blame
 +
| [[#Getting blame result from HEAD]]<br>[[#Getting blame result from commit]] || ||  ||
 +
|-
 +
! branch
 +
| [[#Listing branches]]<br>[[#Getting branch metadata]] || || [[#Creating a branch]] || [[#Removing a branch]]
 +
|-
 +
! clone
 +
| [[#Getting the list of repositories]] || [[#Checking out a branch]]<br>[[#Discarding changes in working directory]] || [[#Creating a repository clone]]<br>[[#Initializing a git repository]] || [[#Removing a clone]]
 +
|-
 +
! commit
 +
| [[#Listing commits]]<br>[[#Listing commits revision or named commits]]<br>[[#Getting commit metadata]]<br>[[#Getting file content in a commit]]<br>[[#Getting a file content from HEAD]]<br>[[#Getting file content in a commit]] || [[#Tagging a commit]] || [[#Committing all files in index]]<br>[[#Amending a commit]]<br>[[#Committing a single file]]<br>[[#Merging changes from a remote to HEAD]]<br>[[#Cherry-picking a commit]] || [[#git rm]]
 +
|-
 +
! config
 +
| [[#Getting repository options]]<br>[[#Getting repository option]] || [[#Updating repository option]] || [[#Setting repository option]] || [[#Unsetting repository option]]
 +
|-
 +
! diff
 +
|[[#Getting a diff between working tree and index]]<br>[[#Getting a diff between index and HEAD]]<br>[[#Getting a diff between two commits]] ||  || [[#Getting a diff location for two commits]] ||
 +
|-
 +
! index
 +
| [[#Getting a file content from index]] || [[#Staging a file]]<br>[[#Staging files]] || [[#Unstaging all files in the index]]<br>[[#Unstaging a single file]]<br>[[#Unstaging a group of files]] ||
 +
|-
 +
! remote
 +
| [[#Getting the list of remotes]]<br>[[#Getting the list of remote's branches]]<br>[[#Getting the remote branch details]] || || [[#Adding a new remote]]<br>[[#Fetching changes from a remote ]]<br>[[#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 commands ==
  
 
=== git add ===
 
=== git add ===
 +
* [[#Staging a file]]
 
* [[#Staging files]]
 
* [[#Staging files]]
* [[#Unstaging files]]
+
* [[#Unstaging a single file]]
 +
* [[#Unstaging all files in the index]]
 +
* [[#Getting a file content from index]]
 +
 
 +
=== git blame ===
 +
* [[#Getting blame result from HEAD]]
 +
* [[#Getting blame result from commit]]
  
 
=== git branch ===
 
=== git branch ===
no bug yet
+
* [[#Listing branches]]
 +
* [[#Getting branch metadata]]
 +
* [[#Creating a branch]]
 +
* [[#Removing a branch]]
  
 
=== git checkout ===
 
=== git checkout ===
see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=339107 bug 337818]
+
* [[#Checking out a branch]]
 +
* [[#Discarding changes in working directory]]
 +
 
 +
=== git cherry-pick ===
 +
*[[#Cherry-picking a commit]]
  
 
=== git clone ===
 
=== git clone ===
see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=337818 bug 337818]
+
*[[#Getting the list of repositories]]
 +
*[[#Creating a repository clone]]
 +
*[[#Initializing a git repository]]
 +
*[[#Removing a clone]]
  
 
=== git config ===
 
=== git config ===
[[#Configuring git]]
+
* [[#Getting repository options]]
 +
* [[#Getting repository option]]
 +
* [[#Updating repository option]]
 +
* [[#Setting repository option]]
 +
* [[#Unsetting repository option]]
  
 
=== git commit ===
 
=== git commit ===
* [[#Committing files in index]]
+
* [[#Committing all files in index]]
 
* [[#Amending a commit]]
 
* [[#Amending a commit]]
* [https://bugs.eclipse.org/bugs/show_bug.cgi?id=339190 Committing a single file]
+
* [[#Committing a single file]]
  
 
=== git diff ===
 
=== git diff ===
* [[#Getting a 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 index]]
 +
* [[#Getting a file content from HEAD]]
  
 
=== git fetch ===
 
=== git fetch ===
see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=339110 bug 339110]
+
* [[#Fetching changes from a remote]]
 +
 
 +
=== git init ===
 +
* [[#Initializing a git repository]]
  
 
=== git log ===
 
=== git log ===
see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=339104 bug 339104]
+
* [[#Listing commits]]
 +
* [[#Listing commits between two named commits]]
 +
* [[#Getting commit metadata]]
 +
* [[#Getting file content in a commit]]
  
 
=== git merge ===
 
=== git merge ===
see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=339111 bug 339111]
+
* [[#Merging changes from a remote to HEAD]]
 +
* Squashing changes - see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=351432 bug 351432]
 +
 
 +
=== git mv ===
 +
 
 +
see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=349168 bug 349168]
  
 
=== git pull ===
 
=== git pull ===
Line 41: Line 118:
  
 
=== git push ===
 
=== git push ===
see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=339115 bug 339115]
+
*[[#Pushing changes to a remote]]
  
 
=== git remote ===
 
=== git remote ===
see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=339109 bug 339109]
+
*[[#Getting the list of remotes]]
 +
*[[#Getting the list of remote's branches]]
 +
*[[#Getting the remote branch details]]
 +
*[[#Adding a new remote]]
 +
*[[#Removing remote]]
  
 
=== git reset ===
 
=== git reset ===
see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=338202 bug 338202]
+
* [[#Unstaging all files in the index]]
 +
* [[#Unstaging a single file]]
 +
* [[#Unstaging a group of files]]
  
 
=== git revert ===
 
=== git revert ===
 
see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=339105 bug 339105]
 
see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=339105 bug 339105]
 +
 +
=== git rm ===
 +
see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=349299 bug 349299]
  
 
=== git status ===
 
=== git status ===
Line 56: Line 142:
  
 
=== git tag ===
 
=== git tag ===
see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=339108 bug 339108]
+
* [[#Tagging a commit]]
 +
* [[#Creating a new tag]]
 +
* [[#Listing tags]]
 +
* [[#Removing a tag]]
  
 
== REST API ==
 
== REST API ==
  
=== Getting status for a git project ===
+
=== Getting the list of repositories ===
  
 
{{Orion/ServerAPI
 
{{Orion/ServerAPI
 
| method = GET
 
| method = GET
| overview = To retrieve the working tree status of a project, send a GET request to the git status location.
+
| overview = To get the list of repositories send a GET request to the git clone location.
| reqhead = /git/status/file/MyProj/
+
| reqhead = /gitapi/clone/workspace/{:workspace_id}/
 +
| reqbody =
 
| resphead = 200 OK
 
| resphead = 200 OK
   Content-Type: text/plain
+
| respbody = 
   Content-Length: 22
+
   {"Children": [
| respbody =    
+
  {
   TBD
+
    "BranchLocation": "http://localhost:8080/gitapi/branch/file/u/",
| explain = TBD.
+
    "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/"
 +
   }
 +
   ]}
 +
| explain = TBD
 
}}
 
}}
  
Progress in being tracked on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=337212 bug 337212].
+
=== Creating a repository clone ===
  
=== Getting a diff ===
+
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To create a clone send a POST request to the git clone location.
 +
| reqhead = /gitapi/clone/
 +
| reqbody =
 +
  {
 +
  "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}"
 +
  }
 +
| resphead = 201 CREATED
 +
| respbody = 
 +
  {
 +
  "Id": "IOOD6ph8ABASBcDqmXX87w",
 +
  "Location": "http://localhost:8080/task/id/IOOD6ph8ABASBcDqmXX87w",
 +
  "Message": "Cloning c:\\home\\clones\\testClone...",
 +
  "PercentComplete": 0,
 +
  "Running": true
 +
  }
 +
| explain = The response contains the location of the git clone task. Call Get on the task location to check the status.
 +
}}
 +
 
 +
=== Initializing a git repository ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| 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.
 +
| reqhead = /gitapi/clone/
 +
| reqbody =
 +
  {
 +
  "Name" : "{repo_name}",
 +
  "Location" : "/workspace/{workspace_id}",
 +
  "GitMail" : "{committer e-mail address}",
 +
  "GitName" : "{committer name}"
 +
  }
 +
| resphead = 201 CREATED
 +
| respbody = 
 +
  {
 +
  "Location": "http://localhost:8080/git/clone/file/user-OrionContent/repo"
 +
  }
 +
| explain = 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 ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = DELETE
 +
| overview = To delete a clone send a DELETE request to the git clone location.
 +
| reqhead = /gitapi/clone/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
| explain = No response. The clone and its folder have been deleted.
 +
}}
 +
 
 +
=== Getting repository options ===
  
 
{{Orion/ServerAPI
 
{{Orion/ServerAPI
 
| method = GET
 
| method = GET
| overview = To retrieve changes between selected commits, commit and working tree, and so on. Send a GET request to the git diff location.
+
| overview = To get the list of repository options send a GET request to the git config location.
| reqhead = /git/diff/file/MyProj/
+
| reqhead = /gitapi/config/clone/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 
| resphead = 200 OK
 
| resphead = 200 OK
   Content-Type: text/plain
+
| respbody =
   Content-Length: 22
+
   {"Children": [
| respbody =    
+
  {
   TBD
+
    "Key": "core.repositoryformatversion",
| explain = TBD.
+
    "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"]
 +
  }
 +
  ]}
 +
  | explain = The response contains the list of all repository options. Each option contains its location, which can be used for update or delete operation.  
 
}}
 
}}
  
=== Getting a file content from index ===
+
=== Getting repository option ===
  
 
{{Orion/ServerAPI
 
{{Orion/ServerAPI
 
| method = GET
 
| method = GET
| overview = To retrieve file content kept in index. Send a GET request to the git index location.
+
| overview = To get the repository option send a GET request to the git config option location.
| reqhead = /git/index/file/MyProj/file.txt
+
| reqhead = /gitapi/config/user.name/clone/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 
| resphead = 200 OK
 
| resphead = 200 OK
   Content-Type: text/plain
+
| respbody =
  Content-Length: 22
+
   {
| respbody =    
+
    "Key": "user.name",
   This is the content.
+
    "Location": "http://localhost:8080/gitapi/config/user.name/clone/file/user-OrionContent/repo/",
| explain = TBD.
+
    "Value": ["John"]
 +
   }
 +
   | explain = The response contains the repository option key, value and location.
 
}}
 
}}
  
 +
=== Updating repository option ===
  
Progress is being tracked on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=337212 bug 337212].
+
{{Orion/ServerAPI
 +
| method = PUT
 +
| overview = To update repository option send a PUT request to the git config option location. POST also can be used, see [[#Setting repository option]].
 +
| reqhead = /gitapi/config/user.name/clone/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
  {
 +
  "Value" : "John"
 +
  }
 +
| resphead = 200 OK
 +
| respbody =
 +
  {
 +
    "Key": "user.name",
 +
    "Location": "http://localhost:8080/gitapi/config/user.name/clone/file/user-OrionContent/repo/",
 +
    "Value": ["John"]
 +
  }
 +
  | explain = The response contains the repository option key, value and location.
 +
}}
 +
 
 +
=== Setting repository option ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To set a new repository option send a POST request to the git config location.
 +
| reqhead = /gitapi/config/clone/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
  {
 +
  "Key" : "user.name",
 +
  "Value" : "Alice"
 +
  }
 +
| resphead = 201 CREATED
 +
| respbody =
 +
  {
 +
    "Key": "user.name",
 +
    "Location": "http://localhost:8080/gitapi/config/user.name/clone/file/user-OrionContent/repo/",
 +
    "Value": ["Alice"]
 +
  }
 +
  | explain = The response contains the repository option key, value and location.
 +
}}
 +
 
 +
=== Unsetting repository option ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = DELETE
 +
| overview = To unset repository option send a DELETE request to the git config option location.
 +
| reqhead = /gitapi/config/user.name/clone/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody =
 +
| explain = No response. The repository option has been unset.
 +
}}
  
 
=== Getting a file content from HEAD ===
 
=== Getting a file content from HEAD ===
Line 112: Line 363:
 
| method = GET
 
| method = GET
 
| overview = To retrieve file content kept in HEAD. Send a GET request to the git commit location.
 
| overview = To retrieve file content kept in HEAD. Send a GET request to the git commit location.
| reqhead = /git/commit/HEAD/file/MyProj/file.txt
+
| reqhead = /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/file.txt
 
| resphead = 200 OK
 
| resphead = 200 OK
 
   Content-Type: text/plain
 
   Content-Type: text/plain
Line 121: Line 372:
 
}}
 
}}
  
=== Configuring git ===
+
=== Committing all files in index ===
  
Progress is being tracked on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=337820 bug 337820].
+
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To commit all files in index. Send a POST request to the git commit location.
 +
| reqhead = /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody = {
 +
"Message" : "fixing bug 349827"
 +
}
 +
| resphead = 200 OK
 +
| respbody = 
 +
{
 +
  "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"
 +
}
 +
| explain = The response will contain a newly created commit.
 +
}}
  
=== Staging files ===
+
=== Amending a commit ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To amend the last commit. Send a POST request to the git commit location.
 +
| reqhead = /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody = {
 +
"Message" : "{amended commit message}",
 +
"Amend" : "true",
 +
"ChangeId" : false,
 +
"AuthorName" : "{author name}",
 +
"AuthorEmail" : "{author email}",
 +
"CommitterName" : "{committer name}",
 +
"CommitterEmail" : "{committer email}",
 +
"persist" : false
 +
}
 +
| resphead = 200 OK
 +
| respbody = 
 +
  see [[#Committing all files in index]]
 +
| explain = TBD.
 +
}}
 +
 
 +
=== Committing a single file ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To commit a single. Send a POST request to the git commit location of that file.
 +
| reqhead = /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/{:file_path}
 +
| reqbody = {
 +
"Message" : "fixing bug 349827"
 +
}
 +
| resphead = 200 OK
 +
| respbody = 
 +
{
 +
  "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"
 +
}
 +
| explain = 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 ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To merge changes from a remote to HEAD send a POST request to the git commit location.
 +
| reqhead = /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 200 OK
 +
| reqbody =
 +
  {
 +
  "Merge" : "{refId}"
 +
  }
 +
| respbody = 
 +
  {"Result": "ALREADY_UP_TO_DATE"}
 +
| explain = TBD.
 +
}}
 +
 
 +
=== Cherry-picking a commit ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To cherry-pick a commit send a POST request to the git commit location.
 +
| reqhead = /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 200 OK
 +
| reqbody =
 +
  {
 +
  "Cherry-Pick" : "e345e82f3e793be3ce872f5784da92f4a9e50007"
 +
  }
 +
| respbody = 
 +
  {"Result": "OK", "HeadUpdated" : "true"}
 +
| explain = 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 ===
  
 
{{Orion/ServerAPI
 
{{Orion/ServerAPI
 
| method = PUT
 
| method = PUT
| overview = To stage a file, add it to index. Send a PUT request to the git index location.
+
| overview = To tag a commit send a PUT request to the git commit location.
| reqhead = /git/index/file/MyProj/file.txt
+
| reqhead = /gitapi/commit/(revision)/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
  {
 +
  "Name" : "{tag name}"
 +
  "Annotated" : "{true or false}"
 +
  "Message" : "{annotated tag message}"
 +
  }
 
| resphead = 200 OK
 
| resphead = 200 OK
 
   Content-Type: text/plain
 
   Content-Type: text/plain
 
   Content-Length: 22
 
   Content-Length: 22
| respbody =   
+
| respbody =
   <nothing>
+
  {
 +
  "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
 +
   }
 
| explain = TBD.
 
| explain = TBD.
 
}}
 
}}
  
 +
=== Removing a tag ===
  
=== Unstaging files ===
+
{{Orion/ServerAPI
 +
| method = DELETE
 +
| overview = To deleta a tag a DELETE request to the git tag location.
 +
| reqhead = /gitapi/tag/tag1/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody =
 +
| explain = No response. The tag has been removed.
 +
}}
 +
 
 +
=== Getting a diff between working tree and index ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To retrieve changes between working tree and index. Send a GET request to the git diff location.
 +
| reqhead = /gitapi/diff/Default/file/{:workspace_id}/{:repo_dir}/
 +
Orion-Version: 1.0
 +
| resphead = HTTP/1.1 200 OK
 +
Content-Type: multipart/related; boundary="BOUNDARY"
 +
ETag: "35fd43td3"
 +
--BOUNDARY
 +
Content-Type: application/json
 +
| respbody =
 +
  {
 +
  "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
 +
| explain = 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 ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To retrieve changes between index and HEAD. Send a GET request to the git diff location.
 +
| reqhead = /gitapi/diff/Cached/file/{:workspace_id}/{:repo_dir}/
 +
Orion-Version: 1.0
 +
| resphead = HTTP/1.1 200 OK
 +
Content-Type: multipart/related; boundary="BOUNDARY"
 +
ETag: "35fd43td3"
 +
--BOUNDARY
 +
Content-Type: application/json
 +
| respbody =
 +
  {
 +
  "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
 +
| explain = 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 ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To retrieve changes between two commits. Send a GET request to the git diff location.
 +
| reqhead = /gitapi/diff/{:old revision}..{:new revision}/file/{:workspace_id}/{:repo_dir}/?parts={:diffs/uris}&pageSize={:page_size}&page={:page_number}
 +
Orion-Version: 1.0
 +
| resphead = HTTP/1.1 200 OK
 +
Content-Type: multipart/related; boundary="BOUNDARY"
 +
ETag: "35fd43td3"
 +
--BOUNDARY
 +
Content-Type: application/json
 +
| respbody =
 +
  {
 +
  "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
 +
| explain = If query parameter "parts=diffs" then "pageSize" and "page" must also be specified.
 +
}}
 +
 
 +
=== Getting a diff location for two commits ===
  
 
{{Orion/ServerAPI
 
{{Orion/ServerAPI
 
| method = POST
 
| method = POST
| overview = To unstage a file, reset index and/or working tree. Send a POST request to the git index location.
+
| overview = To get a diff location for two commits. Send a POST request to the git diff location for old commit.
| reqhead = /git/index/file/MyProj/file.txt
+
| reqhead = /gitapi/diff/{:old revision}/file/{:workspace_id}/{:repo_dir}/{:file_path}
 
| reqbody = {
 
| reqbody = {
  "Reset" : "MIXED"  
+
  "New" : "{new revision}"  
 
  }  
 
  }  
 
| resphead = 200 OK
 
| resphead = 200 OK
 
   Content-Type: text/plain
 
   Content-Type: text/plain
 
   Content-Length: 22
 
   Content-Length: 22
 +
  Location: /git/diff/{old revision}..{new revision}/file/repo/
 
| respbody =   
 
| respbody =   
 
   <nothing>
 
   <nothing>
Line 157: Line 668:
 
}}
 
}}
  
Progress is being tracked on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=338202 bug 338202].
+
=== Getting file content from index ===
  
=== Committing files in index ===
+
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To retrieve file content kept in index. Send a GET request to the git index location.
 +
| reqhead = /gitapi/index/file/{:workspace_id}/{:repo_dir}/{:file_path}
 +
| resphead = 200 OK
 +
  Content-Type: text/plain
 +
  Content-Length: 22
 +
| respbody = 
 +
  This is the content from index.
 +
| explain = TBD.
 +
}}
 +
 
 +
=== Unstage all files in the index ===
  
 
{{Orion/ServerAPI
 
{{Orion/ServerAPI
 
| method = POST
 
| method = POST
| overview = To commit all files in index. Send a POST request to the git commit location.
+
| overview = To unstage all previously-staged files, reset index and/or working tree. Send a POST request to the git index location.
| reqhead = /git/commit/file/MyProj/
+
| reqhead = /gitapi/index/file/{:workspace_id}/{:repo_dir}/
 
| reqbody = {
 
| reqbody = {
  "Message" : "<Your commit message>"  
+
  "Reset" : "MIXED"  
 
  }  
 
  }  
 
| resphead = 200 OK
 
| resphead = 200 OK
  Content-Type: text/plain
 
  Content-Length: 22
 
 
| respbody =   
 
| respbody =   
  <nothing>
+
| explain = No response body. Subsequent request for git status will show that all staged files are now unstaged.
| explain = TBD.
+
 
}}
 
}}
  
=== Amending a commit ===
+
=== Unstaging a group of files ===
  
 
{{Orion/ServerAPI
 
{{Orion/ServerAPI
 
| method = POST
 
| method = POST
| overview = To amend the last commit. Send a POST request to the git commit location.
+
| overview = To unstage a group of files. Send a POST request to the git index location.
| reqhead = /git/commit/file/MyProj/
+
| reqhead = /gitapi/index/file/{:workspace_id}/{:repo_dir}/
 
| reqbody = {
 
| reqbody = {
  "Message" : "<Your commit message>",
+
  "Path" : ["folder/file.txt", "file1.txt" ]
"Amend" : "true"
+
 
  }  
 
  }  
 
| resphead = 200 OK
 
| resphead = 200 OK
 +
| respbody = 
 +
| explain = No response body. Subsequent request for git status will show that the files have been unstaged.
 +
}}
 +
 +
=== Unstaging a single file ===
 +
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To unstage an individual file. Send a POST request to the git index location.
 +
| reqhead = /gitapi/index/file/{:workspace_id}/{:repo_dir}/file.txt
 +
| resphead = 200 OK
 +
| respbody = 
 +
| explain = No response body. Subsequent request for git status will show that the file has been unstaged.
 +
}}
 +
 +
=== Staging a file ===
 +
 +
{{Orion/ServerAPI
 +
| method = PUT
 +
| overview = To stage a file, add it to the index. Send a PUT request to the git index location.
 +
| reqhead = /gitapi/index/file/{:workspace_id}/{:repo_dir}/{:file_path}
 +
| resphead = 200 OK
 +
| respbody = 
 +
| explain = No response body, see [[#Getting status for a git project]] to verify the file has been added to index.
 +
}}
 +
 +
=== Staging files ===
 +
 +
{{Orion/ServerAPI
 +
| method = PUT
 +
| overview = To stage multiple files, add them to the index. Send a PUT request to the git index location.
 +
| reqhead = /gitapi/index/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
  {
 +
  "Path" : ["file1.txt", "folder/file.txt"]
 +
  }
 +
| resphead = 200 OK
 +
| respbody =
 +
| explain = No response body, see [[#Getting status for a git project]] to verify all files have been added to index.
 +
}}
 +
 +
=== Getting the list of remotes ===
 +
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To get the list of remotes send a GET request to the git remote location.
 +
| reqhead = /gitapi/remote/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
{
 +
  "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"
 +
}
 +
| explain = TBD
 +
}}
 +
 +
=== Getting the list of a remote's branches ===
 +
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To get the list of a remote's branches send a GET request to the git remote location.
 +
| reqhead = /gitapi/remote/{:remote}/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
  {
 +
  "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"
 +
  }
 +
| explain = TBD
 +
}}
 +
 +
=== Getting the remote branch details ===
 +
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To get the remote branch details send a GET request to the git remote location.
 +
| reqhead = /gitapi/remote/{:remote}/{:branch}/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
  {
 +
  "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/"
 +
  }
 +
| explain = TBD
 +
}}
 +
 +
=== Adding a new remote ===
 +
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To add a new remote send a POST request to the git remote location.
 +
| reqhead = /gitapi/remote/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
  {
 +
  "Remote" : "{remote name}",
 +
  "RemoteURI" : "{remote URI}",
 +
  "FetchRefSpec" : "{fetch refspec - optional}",
 +
  "PushURI" : "{remote push URI - optional}",
 +
  "PushRefSpec" : "{push refspec - optional}"
 +
  }
 +
| resphead = 201 CREATED
 +
  Location: http://localhost:8080/git/remote/newremote/file/repo/
 +
  Content-Type: application/json
 +
| respbody = 
 +
  {
 +
    "Location": "http://localhost:8080/git/remote/newremote/file/repo/"
 +
  }
 +
}
 +
| explain = The response contain the location of the new remote.
 +
}}
 +
 +
=== Fetching changes from a remote ===
 +
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To fetch changes from a remote send a POST request to the git branch location.
 +
| reqhead = /gitapi/remote/{:remote}/{:branch}/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 201 CREATED
 +
| reqbody =
 +
  {
 +
  "Fetch" : "true",
 +
  "GitSshKnownHost" : "{git ssh known host}",
 +
  "GitSshUsername" : "{git ssh username}",
 +
  "GitSshPassword" : "{git ssh password}",
 +
  "GitSshPrivateKey" : "{git ssh private key}",
 +
  "GitSshPassphrase" : "{git ssh passphrase}"
 +
  }
 +
| respbody = 
 +
  {
 +
  "Id": "QEHCv6J8ABASBcDqmXX87w",
 +
  "Location": "http://localhost:8080/task/id/QEHCv6J8ABASBcDqmXX87w",
 +
  "Message": "Fetching origin...",
 +
  "PercentComplete": 0,
 +
  "Running": true
 +
  }
 +
| explain = 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 ===
 +
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To push changes from a remote send a POST request to the git branch location.
 +
| reqhead = /gitapi/remote/{:remote}/{:branch}/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 201 CREATED
 +
| reqbody =
 +
  {
 +
  "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}"
 +
  }
 +
| respbody = 
 +
  {
 +
  "Id": "YLhATqR8ABASBcDqmXX87w",
 +
  "Location": "http://localhost:8080/task/id/YLhATqR8ABASBcDqmXX87w",
 +
  "Message": "Pushing origin...",
 +
  "PercentComplete": 0,
 +
  "Running": true
 +
  }
 +
| explain = The response contain the location of the git push task. Call Get on the task location to check the status.
 +
}}
 +
 +
=== Removing remotes ===
 +
 +
{{Orion/ServerAPI
 +
| method = DELETE
 +
| overview = To delete the remote send a DELETE request to the git remote location.
 +
| reqhead = /gitapi/remote/{:remote}/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
| explain = HTTP status code 200 OK is returned, when the remote is successfully removed.
 +
}}
 +
 +
=== Getting status for a git project ===
 +
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To retrieve the working tree status of a project, send a GET request to the git status location.
 +
| reqhead = /gitapi/status/file/{:workspace_id}/{:repo_dir}/
 +
| resphead = 200 OK
 +
  Content-Type: application/json; charset=UTF-8
 +
  Content-Length: 468
 +
| respbody = 
 +
  {
 +
  "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": []
 +
  }
 +
| explain = "IndexLocation" can be used to add all files to index, "CommitLocation" can be used to commit all files.
 +
}}
 +
 +
=== Creating a new tag ===
 +
 +
{{Orion/ServerAPI
 +
| method = PUT
 +
| overview = To tag a commit send a PUT request to the git tag location.
 +
| reqhead = /gitapi/commit/{:refId}/file/{:workspace_id}/{:repo_dir}
 +
| reqbody =
 +
  {
 +
  "Name" : "{tag name}",
 +
  "Annotated" : boolean,
 +
  "Message" : "{annotated message}",
 +
  }
 +
| resphead = 201 CREATED
 
   Content-Type: text/plain
 
   Content-Type: text/plain
 
   Content-Length: 22
 
   Content-Length: 22
| respbody =  
+
| respbody = TBD
  <nothing>
+
| explain = TBD
| explain = TBD.
+
 
}}
 
}}
  
This operation is not yet supported, see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=339242 bug 339242].
+
=== Listing tags ===
  
= JSON representations =
+
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To get the list of tags send a GET request to the git tag location.
 +
| reqhead = /gitapi/tag/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
  {
 +
  "Children": [
 +
    {
 +
      "FullName": "refs/tags/v20110606",
 +
      "Name": "v20110606"
 +
    },
 +
    {
 +
      "FullName": "refs/tags/v20110607",
 +
      "Name": "v20110607"
 +
    },
 +
    {
 +
      "FullName": "refs/tags/R0_2M4",
 +
      "Name": "vR0_2M4"
 +
    }
 +
  ]}
 +
| explain = The response contains list of all tags for the given repository.
 +
}}
 +
 
 +
=== Listing branches ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To get the list of branches send a GET request to the git tag location.
 +
| reqhead = /gitapi/branch/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
  {
 +
  "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"
 +
    }
 +
  ]}
 +
| explain = 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 ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To get more info about a branch send a GET request to its git branch location.
 +
| reqhead = /gitapi/branch/master/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
  {
 +
    "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"
 +
  }
 +
| explain = The response contains details of the selected local branch.
 +
}}
 +
 
 +
=== Creating a branch ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To create a local send a POST request to the git BranchLocation. The data must be JSON.
 +
| reqhead = /gitapi/branch/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 201 CREATED
 +
| reqbody =
 +
  {
 +
  "Name" : "dev",
 +
  "Branch" : "{starting point}" (if omitted the current HEAD will be used)
 +
  }
 +
| respbody = 
 +
  {
 +
  "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"
 +
  }
 +
| explain = 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 ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = DELETE
 +
| overview = To remove a local branch send a DELETE request to its git branch location.
 +
| reqhead = /gitapi/branch/master/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody =
 +
| explain = The response is empty. Subsequent calls on the branch location will return 404 NOT FOUND.
 +
}}
 +
 
 +
=== Checking out a branch ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = PUT
 +
| overview = To checkout a branch send a PUT request to the git clone Location. The data must be JSON.
 +
| reqhead = /gitapi/clone/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
  {
 +
  "Branch" : "dev"
 +
  }
 +
| resphead = 200 OK
 +
| respbody =
 +
| explain = No response body, but subsequent requests for branch details will indicate that 'dev' is now an active (current) branch.
 +
}}
 +
 
 +
=== Checking out a tag ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = PUT
 +
| overview = To checkout a tag send a PUT request to the git clone location. A new branch will be created for the requested tag.
 +
| reqhead = /gitapi/clone/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
  {
 +
  "Tag" : "stable"
 +
  "Branch" : "tag_stable"
 +
  }
 +
| resphead = 200 OK
 +
| respbody =
 +
| explain = 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 ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = PUT
 +
| overview = To checkout a file send a PUT request to the git clone location.
 +
| reqhead = /gitapi/clone/file/{:workspace_id}/{:repo_dir}/
 +
| reqbody =
 +
  {
 +
  "Path" : ["folder/file.txt"]
 +
  }
 +
| resphead = 200 OK
 +
| respbody =
 +
| explain = No response body, but subsequent request for the file content will show that its content has been replaced with the index.
 +
}}
 +
 
 +
=== Listing commits ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To get list of commits (log) send a GET request to the HeadLocation.
 +
| reqhead = /gitapi/commit/HEAD/file/{:workspace_id}/{:repo_dir}/?parts=log
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
{
 +
  "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"
 +
  }
 +
}
 +
| explain = 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 ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To get list of commits (log) using a [http://schacon.github.com/git/gitrevisions.html 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.
 +
| reqhead = /gitapi/commit/master~4..master/file/{:workspace_id}/{:repo_dir}
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
{
 +
  "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"
 +
  }
 +
}
 +
| explain = The response contains an array of commits on the Children property.
 +
}}
 +
 
 +
=== Getting commit metadata ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To get details of a commit send a GET request to git commit location.
 +
| reqhead =  /gitapi/commit/c47c36518cd8aaf01b84afa55cf9a75badc882d9/file/{:workspace_id}/{:repo_dir}/{:file_path}
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
{
 +
  "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": ""
 +
}
 +
| explain = The response contains details for the selected commit.
 +
}}
 +
 
 +
=== Getting file content in a commit ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To retrieve file content kept for a specific commit. Send a GET request to the git commit location.
 +
| reqhead =  /gitapi/commit/c47c36518cd8aaf01b84afa55cf9a75badc882d9/file/{:workspace_id}/{:repo_dir}/{:file_path}?parts=body
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
  I'm content of file.txt
 +
| explain = The response contains content of the selected file in the given commit.
 +
}}
 +
 
 +
=== Getting blame result from HEAD ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = Retrieve blame information for the specified file from HEAD.
 +
| reqhead =  /gitapi/blame/HEAD/file/{:workspace_id}/{:repo_dir}/{:file_path}
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
{
 +
  "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"
 +
}
 +
| explain = 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 ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = Retrieve blame information for the specified file for a commit.
 +
| reqhead =  /gitapi/blame/{:sha}/file/{:workspace_id}/{:repo_dir}/{:file_path}
 +
| reqbody =
 +
| resphead = 200 OK
 +
| respbody = 
 +
{
 +
  "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"
 +
}
 +
 
 +
| explain = The response contains the blame information for a file for a certain commit. See [[#Getting blame result from HEAD]]
 +
}}
 +
 
 +
== JSON representations ==
  
== File representation extension  ==
+
=== File representation extension  ===
  
 
The [[Orion/Server API/File_API#JSON representations|JSON representation for files and directories]] used by [[Orion/Server_API/File_API|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.  
 
The [[Orion/Server API/File_API#JSON representations|JSON representation for files and directories]] used by [[Orion/Server_API/File_API|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.  
Line 207: Line 1,370:
 
! Data type  
 
! Data type  
 
! Value
 
! Value
 +
|-
 +
| Git.CommitLocation
 +
| URI
 +
| Location of Git Commit resource (HEAD)
 +
|-
 +
| Git.DefaultRemotebranchLocation
 +
| URI
 +
| Location of the default remote branch
 
|-
 
|-
 
| Git.DiffLocation
 
| Git.DiffLocation
 
| URI  
 
| URI  
 
| Location of Git Diff resource
 
| Location of Git Diff resource
 +
|-
 +
| Git.IndexLocation
 +
| URI
 +
| Location of Git Index resource
 +
|-
 +
| Git.RemoteLocation
 +
| URI
 +
| Location of Git Remote resource
 
|-
 
|-
 
| Git.StatusLocation
 
| Git.StatusLocation
Line 216: Line 1,395:
 
| Location of Git Status resource
 
| Location of Git Status resource
 
|-
 
|-
| Git.IndexLocation
+
| Git.TagLocation
 
| URI  
 
| URI  
| Location of Git Index resource
+
| Location of Git Tag resource
 
|}
 
|}
  
 
[[Category:Orion/API|Git API]]
 
[[Category:Orion/API|Git API]]
 
[[Category:Orion/Server API|Git API]]
 
[[Category:Orion/Server API|Git API]]

Latest revision as of 12:10, 20 December 2017

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

Back to the top