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.
Difference between revisions of "Orion/Server API/Git API"
< Orion | Server API
(→Resource/HTTP method matrix) |
(→POST) |
||
| Line 144: | Line 144: | ||
"Running": true | "Running": true | ||
} | } | ||
| − | | explain = The response | + | | 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 = /git/clone/ | ||
| + | | reqbody = | ||
| + | { | ||
| + | "Name" : "d", | ||
| + | "Location" : "/workspace/A", | ||
| + | "Path" : "/file/d", | ||
| + | } | ||
| + | | resphead = 201 CREATED | ||
| + | | respbody = | ||
| + | { | ||
| + | "Location": "http://localhost:8080/git/clone/file/d" | ||
| + | } | ||
| + | | 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). | ||
}} | }} | ||
Revision as of 19:49, 31 May 2011
The Git API is a web server API for browsing and manipulating Git repositories.
git URIs format change
Please note, that once bug 339854 is fixed all URIs listed below will have a slightly different form. I will try to update the page ASAP.
Please note, that once bug 339854 is fixed all URIs listed below will have a slightly different form. I will try to update the page ASAP.
Contents
Git commands
git add
git branch
see bug 341384
git checkout
see bug 337818
git clone
see bug 337818
git config
git commit
git diff
- #Getting a diff between working tree and index
- #Getting a diff between index and HEAD
- #Getting a diff location for two commits
- #Getting a diff between two commits
- #Getting a file content from index
- #Getting a file content from HEAD
git fetch
see bug 339110
git log
see bug 339104
git merge
see bug 339111
git pull
see bug 339114
git push
see bug 339115
git remote
see bug 339109
git reset
see bug 338202
git revert
see bug 339105
git status
#Getting status for a git project
git tag
see bug 339108
REST API
/git/clone/
GET
Getting the list of repositories
- Overview
- To get the list of repositories send a GET request to the git clone location.
- HTTP Method
- GET
- Example Request
GET /git/clone/
- Example Response
HTTP/1.1 200 OK {"Children": [ { "ContentLocation": "file:/C:/home/workspaces/foo/.userarea/x/.gitclone/d", "Id": "d", "Location": "http://localhost:8080/git/clone/d", "Name": "c:\\home\\clones\\testClone" }, { "ContentLocation": "file:/C:/home/workspaces/foo/.userarea/x/.gitclone/b", "Id": "b", "Location": "http://localhost:8080/git/clone/b", "Name": "c:\\home\\clones\\testClone" }, { "ContentLocation": "file:/C:/home/workspaces/foo/.userarea/x/.gitclone/c", "Id": "c", "Location": "http://localhost:8080/git/clone/c", "Name": "c:\\home\\clones\\testClone" }, { "ContentLocation": "file:/C:/home/workspaces/foo/.userarea/x/.gitclone/a", "Id": "a", "Location": "http://localhost:8080/git/clone/a", "Name": "c:\\home\\clones\\testClone" } ]}
- Detailed Explanation
- TBD
POST
Creating a repository clone
- Overview
- To create a clone send a POST request to the git clone location.
- HTTP Method
- POST
- Example Request
POST /git/clone/
{
"GitUrl" : "{git repo url}",
"GitSshKnownHost" : "{git ssh known host}",
"GitSshUsername" : "{git ssh username}",
"GitSshPassword" : "{git ssh password}",
"GitSshKnownHost" : "{git ssh known host}",
"GitSshPrivateKey" : "{git ssh private key}",
"GitSshPassphrase" : "{git ssh passphrase}"
}
- Example Response
HTTP/1.1 201 CREATED { "Id": "IOOD6ph8ABASBcDqmXX87w", "Location": "http://localhost:8080/task/id/IOOD6ph8ABASBcDqmXX87w", "Message": "Cloning c:\\home\\clones\\testClone...", "PercentComplete": 0, "Running": true }
- Detailed Explanation
- The response contains the location of the git clone task. Call Get on the task location to check the status.
Initializing a git repository
- Overview
- To init a git repository send a POST request to the git clone location. JSON data cannot contain GitUrl field, as it indicates that desired operation is cloning of a repository.
- HTTP Method
- POST
- Example Request
POST /git/clone/
{
"Name" : "d",
"Location" : "/workspace/A",
"Path" : "/file/d",
}
- Example Response
HTTP/1.1 201 CREATED { "Location": "http://localhost:8080/git/clone/file/d" }
- Detailed Explanation
- The response contains the location of the initialized git repository. Call Get on this location to obtain more repository details. Request body can contain either "Name" and "Location" fields (a new project with git repository will be created in the given workspace) or "Path" field only (git repository will be created in the given project).
/git/commit/
GET
Getting a file content from HEAD
- Overview
- To retrieve file content kept in HEAD. Send a GET request to the git commit location.
- HTTP Method
- GET
- Example Request
GET /git/commit/HEAD/file/MyProj/file.txt
- Example Response
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 22
This is the content.
- Detailed Explanation
- TBD.
POST
Committing all files in index
- Overview
- To commit all files in index. Send a POST request to the git commit location.
- HTTP Method
- POST
- Example Request
POST /git/commit/file/MyProj/
{
"Message" : "{Your commit message}"
}
- Example Response
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 22
<nothing>
- Detailed Explanation
- TBD.
Amending a commit
- Overview
- To amend the last commit. Send a POST request to the git commit location.
- HTTP Method
- POST
- Example Request
POST /git/commit/file/MyProj/
{
"Message" : "{Your (amended) commit message}",
"Amend" : "true"
}
- Example Response
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 22
<nothing>
- Detailed Explanation
- TBD.
Merging changes from a remote to HEAD
- Overview
- To merge changes from a remote to HEAD send a POST request to the git commit location.
- HTTP Method
- POST
- Example Request
POST /git/commit/HEAD/file/E/
{
"Merge" : "(refId)"
}
- Example Response
HTTP/1.1 200 OK
{"Result": "ALREADY_UP_TO_DATE"}
- Detailed Explanation
- TBD.
PUT
Tagging a commit
- Overview
- To tag a commit send a PUT request to the git commit location.
- HTTP Method
- PUT
- Example Request
PUT /git/commit/(revision)/file/MyProj/
{
"Name" : "{tag name}"
}
- Example Response
HTTP/1.1 200 OK Content-Type: text/plain Content-Length: 22 { "AuthorName": "(author)", "Children": ["(tag name)"], "ContentLocation": "http://localhost:8080/git/commit/(revision)/file/MyProj/?parts=body", "DiffLocation": "http://localhost:8080/git/diff/(revision)/file/MyProj/", "Location": "http://localhost:8080/git/commit/(revision)/file/MyProj/", "Message": "(commit message)", "Name": "(commit name)", "Time": 1304073355000 }
- Detailed Explanation
- TBD.
/git/config/
Configuring git
Progress is being tracked on bug 337820.
/git/diff/
GET
Getting a diff between working tree and index
- Overview
- To retrieve changes between working tree and index. Send a GET request to the git diff location.
- HTTP Method
- GET
- Example Request
GET /git/diff/Default/file/MyProj/
Orion-Version: 1.0
- Example Response
HTTP/1.1 HTTP/1.1 200 OK Content-Type: multipart/related; boundary="BOUNDARY" ETag: "35fd43td3" --BOUNDARY Content-Type: application/json {"Git": {"Base":"http://localhost:8080/git/index/file/E/a.txt", "DiffLocation":"http://localhost:8080/git/diff/Default/file/E/a.txt", "New":"http://localhost:8080/file/E/a.txt", "Old":"http://localhost:8080/git/index/file/E/a.txt" } } --BOUNDARY Content-Type: plain/text diff --git a/a.txt b/a.txt index 380e08d..bbfd849 100644 --- a/a.txt +++ b/a.txt @@ -1,3 +1,4 @@ fdsfdsafdsad asasasa2d -Elod +Elod +Something
- Detailed Explanation
- The diff and related uris are returned as a single multi-part response. You may use query parts=uris or parts=diff to get only one part of the response.
Getting a diff between index and HEAD
- Overview
- To retrieve changes between index and HEAD. Send a GET request to the git diff location.
- HTTP Method
- GET
- Example Request
GET /git/diff/Cached/file/MyProj/
Orion-Version: 1.0
- Example Response
HTTP/1.1 HTTP/1.1 200 OK Content-Type: multipart/related; boundary="BOUNDARY" ETag: "35fd43td3" --BOUNDARY Content-Type: application/json {"Git": {"Base":"http://localhost:8080/git/index/file/E/a.txt", "DiffLocation":"http://localhost:8080/git/diff/Default/file/E/a.txt", "New":"http://localhost:8080/file/E/a.txt", "Old":"http://localhost:8080/git/index/file/E/a.txt" } } --BOUNDARY Content-Type: plain/text diff --git a/a.txt b/a.txt index 380e08d..bbfd849 100644 --- a/a.txt +++ b/a.txt @@ -1,3 +1,4 @@ fdsfdsafdsad asasasa2d -Elod +Elod +Something
- Detailed Explanation
- The diff and related uris are returned as a single multi-part response. You may use query parts=uris or parts=diff to get only one part of the response.
Getting a diff between two commits
- Overview
- To retrieve changes between two commits. Send a GET request to the git diff location.
- HTTP Method
- GET
- Example Request
GET /git/diff/{old revision}..{new revision}/file/MyProj/
Orion-Version: 1.0
- Example Response
HTTP/1.1 HTTP/1.1 200 OK Content-Type: multipart/related; boundary="BOUNDARY" ETag: "35fd43td3" --BOUNDARY Content-Type: application/json {"Git": {"Base":"http://localhost:8080/git/index/file/E/a.txt", "DiffLocation":"http://localhost:8080/git/diff/Default/file/E/a.txt", "New":"http://localhost:8080/file/E/a.txt", "Old":"http://localhost:8080/git/index/file/E/a.txt" } } --BOUNDARY Content-Type: plain/text diff --git a/a.txt b/a.txt index 380e08d..bbfd849 100644 --- a/a.txt +++ b/a.txt @@ -1,3 +1,4 @@ fdsfdsafdsad asasasa2d -Elod +Elod +Something
- Detailed Explanation
- The diff and related uris are returned as a single multi-part response. You may use query parts=uris or parts=diff to get only one part of the response.
POST
Getting a diff location for two commits
- Overview
- To get a diff location for two commits. Send a POST request to the git diff location for old commit.
- HTTP Method
- POST
- Example Request
POST /git/diff/{old revision}/file/MyProj/file.txt
{
"New" : "{new revision}"
}
- Example Response
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 22
Location: /git/diff/{old revision}..{new revision}/file/MyProj/file.txt
<nothing>
- Detailed Explanation
- TBD.
/git/index/
GET
Getting a file content from index
- Overview
- To retrieve file content kept in index. Send a GET request to the git index location.
- HTTP Method
- GET
- Example Request
GET /git/index/file/MyProj/file.txt
- Example Response
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 22
This is the content from index.
- Detailed Explanation
- TBD.
POST
Unstaging files
- Overview
- To unstage a file, reset index and/or working tree. Send a POST request to the git index location.
- HTTP Method
- POST
- Example Request
POST /git/index/file/MyProj/file.txt
{
"Reset" : "MIXED"
}
- Example Response
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 22
<nothing>
- Detailed Explanation
- TBD.
PUT
Staging files
- Overview
- To stage a file, add it to index. Send a PUT request to the git index location.
- HTTP Method
- PUT
- Example Request
PUT /git/index/file/MyProj/file.txt
- Example Response
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 22
<nothing>
- Detailed Explanation
- TBD.
/git/remote/
GET
Getting the list of remotes
- Overview
- To get the list of remotes send a GET request to the git remote location.
- HTTP Method
- POST
- Example Request
POST /git/remote/file/E/
- Example Response
HTTP/1.1 200 OK {"Children": [{ "Location": "http://localhost:8080/git/remote/origin/file/E/", "Name": "origin" }]}
- Detailed Explanation
- TBD
Getting the list of remote's branches
- Overview
- To get the list of remote's branches send a GET request to the git remote location.
- HTTP Method
- GET
- Example Request
GET /git/remote/(remote)/file/E/
- Example Response
HTTP/1.1 200 OK { "Children": [{ "CommitLocation": "http://localhost:8080/git/commit/bbbcc34fe10c2d731e7f97618f4f469c2f763a31/file/E/", "Id": "bbbcc34fe10c2d731e7f97618f4f469c2f763a31", "Location": "http://localhost:8080/git/remote/origin/master/file/E/", "Name": "refs/remotes/origin/master" }], "Location": "http://localhost:8080/git/remote/origin/file/E/", "Name": "origin" }
- Detailed Explanation
- TBD
Getting the remote branch details
- Overview
- To get the remote branch details send a GET request to the git remote location.
- HTTP Method
- GET
- Example Request
GET /git/remote/(remote)/(branch)/file/E/
- Example Response
HTTP/1.1 200 OK { "CommitLocation": "http://localhost:8080/git/commit/bbbcc34fe10c2d731e7f97618f4f469c2f763a31/file/E/", "HeadLocation": "http://localhost:8080/git/commit/HEAD/file/E/", "Id": "bbbcc34fe10c2d731e7f97618f4f469c2f763a31", "Location": "http://localhost:8080/git/remote/origin/master/file/E/" }
- Detailed Explanation
- TBD
POST
Adding a new remote
- Overview
- To add a new remote send a POST request to the git remote location.
- HTTP Method
- POST
- Example Request
POST /git/remote/file/E/
{
"Remote" : "{remote name}",
"RemoteURI" : "{remote URI}",
"FetchRefSpec" : "{fetch refspec - optional}",
"PushURI" : "{remote push URI - optional}",
"PushRefS[ec" : "{push refspec - optional}"
}
- Example Response
HTTP/1.1 201 CREATED Location: http://localhost:8080/git/remote/newremote/file/E/ Content-Type: application/json { "Location": "http://localhost:8080/git/remote/newremote/file/E/" }
}
- Detailed Explanation
- The response contain the location of the new remote.
Fetching changes from a remote
- Overview
- To fetch changes from a remote send a POST request to the git branch location.
- HTTP Method
- POST
- Example Request
POST /git/remote/(remote)/(branch)/file/E/
{
"Fetch" : "true",
"GitSshKnownHost" : "{git ssh known host}",
"GitSshUsername" : "{git ssh username}",
"GitSshPassword" : "{git ssh password}",
"GitSshKnownHost" : "{git ssh known host}",
"GitSshPrivateKey" : "{git ssh private key}",
"GitSshPassphrase" : "{git ssh passphrase}"
}
- Example Response
HTTP/1.1 201 CREATED { "Id": "QEHCv6J8ABASBcDqmXX87w", "Location": "http://localhost:8080/task/id/QEHCv6J8ABASBcDqmXX87w", "Message": "Fetching origin...", "PercentComplete": 0, "Running": true }
- Detailed Explanation
- The response contain the location of the git fetch task. Call Get on the task location to check the status.
Pushing changes to a remote
- Overview
- To push changes from a remote send a POST request to the git branch location.
- HTTP Method
- POST
- Example Request
POST /git/remote/(remote)/(branch)/file/E/
{
"PushSrcRef" : "HEAD",
"PushTags" : "true"
"GitSshKnownHost" : "{git ssh known host}",
"GitSshUsername" : "{git ssh username}",
"GitSshPassword" : "{git ssh password}",
"GitSshKnownHost" : "{git ssh known host}",
"GitSshPrivateKey" : "{git ssh private key}",
"GitSshPassphrase" : "{git ssh passphrase}"
}
- Example Response
HTTP/1.1 201 CREATED { "Id": "YLhATqR8ABASBcDqmXX87w", "Location": "http://localhost:8080/task/id/YLhATqR8ABASBcDqmXX87w", "Message": "Pushing origin...", "PercentComplete": 0, "Running": true }
- Detailed Explanation
- The response contain the location of the git push task. Call Get on the task location to check the status.
DELETE
Removing remotes
- Overview
- To delete the remote send a DELETE request to the git remote location.
- HTTP Method
- DELETE
- Example Request
DELETE /git/remote/(remote)/file/E/
- Example Response
HTTP/1.1 200 OK
- Detailed Explanation
- HTTP status code 200 OK is returned, when the remote is successfully removed.
/git/status/
GET
Getting status for a git project
- Overview
- To retrieve the working tree status of a project, send a GET request to the git status location.
- HTTP Method
- GET
- Example Request
GET /git/status/file/A/folder/
- Example Response
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 468 { "Added": [], "Changed": [], "CommitLocation": "http://localhost:8080/git/commit/HEAD/file/E/", "Conflicting": [], "IndexLocation": "http://localhost:8080/git/index/file/E/", "Missing": [], "Modified": [{ "Git": { "CommitLocation": "http://localhost:8080/git/commit/HEAD/file/E/a.txt", "DiffLocation": "http://localhost:8080/git/diff/Default/file/E/a.txt", "IndexLocation": "http://localhost:8080/git/index/file/E/a.txt" }, "Location": "http://localhost:8080/file/E/a.txt", "Name": "a.txt", "Path": "a.txt" }], "Removed": [], "Untracked": [] }
- Detailed Explanation
- "IndexLocation" can be used to add all files to index, "CommitLocation" can be used to commit all files.
/git/tag/
POST
Tagging a commit
- Overview
- To tag a commit send a POST request to the git tag location.
- HTTP Method
- POST
- Example Request
POST /git/tag/
{
"Name" : "(tag name)",
"Commit" : "{refId}"
}
- Example Response
HTTP/1.1 201 CREATED
Content-Type: text/plain
Content-Length: 22
TBD
- Detailed Explanation
- TBD
GET
Getting the list of tags
- Overview
- To get the list of tags send a GET request to the git tag location.
- HTTP Method
- GET
- Example Request
GET /git/tag/file/E/
- Example Response
HTTP/1.1 200 OK
TBD
- Detailed Explanation
- TBD
JSON representations
File representation extension
The JSON representation for files and directories used by file API may be extended as follows: Required fields are shown in bold. A client cannot rely on the existence of non-required attribute in a file representation from a given Orion server.
| Field | Data type | Value |
|---|---|---|
| Git.CommitLocation | URI | Location of Git Commit resource (HEAD) |
| Git.DefaultRemotebranchLocation | URI | Location of the default remote branch |
| Git.DiffLocation | URI | Location of Git Diff resource |
| Git.IndexLocation | URI | Location of Git Index resource |
| Git.RemoteLocation | URI | Location of Git Remote resource |
| Git.StatusLocation | URI | Location of Git Status resource |
| Git.TagLocation | URI | Location of Git Tag resource |
Resource/HTTP method matrix
| GET | PUT | POST | DELETE | |
|---|---|---|---|---|
| commit | #git log | ? | #git commit, #git merge (#git pull) | git rm |
| index | #Getting a file content from index | #git add | #git reset | ? |
| clone | list clones, get clone info | ? | create clone | delete clone |
| config | #git config get | #git config set | #git config update | #git config unset |
| branch | #git branch | #git branch | #git branch | #git branch |
| tag | #git tag | #git tag | #git tag | #git tag |
| remote | #git remote | #git remote | #git remote, add remote, fetch, push | remove remote |
| 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 | ? | prepare git diff location | ? |
| status | #Getting status for a git project | ? | ? | ? |