Git and GitHub

The Git state of a session’s folder and every Git action of the review panel; GitHub pull requests through gh. Paths are relative to /api/v1.

GET /sessions/{sessionId}/git/status

The Git status of the session’s folder: staged, unstaged, untracked and conflicting files.

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/git/branch

The current branch of the session’s folder.

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/git/diff

The diff of one file, staged or not.

Path

sessionId

The session.

Query

percorsorequired

the file, relative to the repository.

arearequired

preparato (staged) or lavoro (working tree).

Answers The JSON envelope.

Errors1

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/git/log

The history of commits of the current branch.

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/git/branches

The local branches.

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/git/stashes

The changes set aside (stashes).

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/git/remotes

The remotes of the repository: name and fetch address.

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/git/sync

The synchronization state of the current branch: its upstream, commits ahead and behind, the last fetch, and the remote a push goes to.

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/git/changes

The files a commit changed (or the files changed between two commits).

Path

sessionId

The session.

Query

arequired

the commit.

da

The commit to compare from (default: its parent).

Answers The JSON envelope.

Errors1

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/git/changes-diff

The diff of one file in a commit (or between two commits).

Path

sessionId

The session.

Query

arequired

the commit.

percorsorequired

the file.

da

The commit to compare from (default: its parent).

prima

The file’s earlier path, when it was renamed.

Answers The JSON envelope.

Errors1

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.

Any operation can also answer the common errors.

GET /github/status

Whether the GitHub CLI (gh) that TALOS uses is installed, and whether an account is connected.

Answers The JSON envelope.

Errors1

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.

Any operation can also answer the common errors.

POST /github/install

Download TALOS’s own copy of the GitHub CLI (gh).

Body

None: the body is empty.

Answers The JSON envelope.

Errors3

Code	Status	Meaning
GH_STORE_UNAVAILABLE	503	GitHub is not available on this server.
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /github/login

Connect a GitHub account with the device flow: answers the code to enter on GitHub.

Body

None: the body is empty.

Answers The JSON envelope.

Errors3

Code	Status	Meaning
GH_STORE_UNAVAILABLE	503	GitHub is not available on this server.
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /github/login-cancel

Cancel a GitHub connection in progress.

Body

None: the body is empty.

Answers The JSON envelope.

Errors3

Code	Status	Meaning
GH_STORE_UNAVAILABLE	503	GitHub is not available on this server.
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/github/pulls

The pull requests of the current branch and the open ones of the repository.

Path

sessionId

The session.

Answers The JSON envelope.

Errors1

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/github/pulls

Open a pull request from the current branch, which must already be pushed (pushing has its own confirmation; this never pushes).

Path

sessionId

The session.

Body

titolo

The title.

testo

The description (default empty).

base

The branch to merge into.

bozza

true to open it as a draft.

Answers The JSON envelope.

Errors3

Code	Status	Meaning
GH_STORE_UNAVAILABLE	503	GitHub is not available on this server.
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/github/pull-draft

A draft of the pull request form for the current branch: title, description and base.

Path

sessionId

The session.

Query

base

The branch to compare with (once at most).

Answers The JSON envelope.

Errors1

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/github/pulls/{pullNumber}/checks

The checks (CI) of a pull request.

The number is digits only, without leading zeros, at most nine.

Path

sessionId

The session.

pullNumber

The pull request number.

Answers The JSON envelope.

Errors1

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/stage

Stage files.

Path

sessionId

The session.

Body

percorsi

The files, relative to the repository.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/unstage

Unstage files.

Path

sessionId

The session.

Body

percorsi

The files, relative to the repository.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/commit

Commit files with a message.

Path

sessionId

The session.

Body

percorsi

The files to commit.

messaggio

The commit message.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/discard

Discard the changes of files in the working tree.

Path

sessionId

The session.

Body

percorsi

The files.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/commit-staged

Commit what is staged.

Path

sessionId

The session.

Body

messaggio

The commit message.

impronta

The fingerprint of the staged changes the window saw: if they changed since, nothing is committed.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/amend

Amend the last commit.

Path

sessionId

The session.

Body

messaggio

The new message.

impronta

The fingerprint of the staged changes the window saw.

commit

The commit the window saw as the last one.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/undo-commit

Undo the last commit, keeping its changes.

Path

sessionId

The session.

Body

commit

The commit the window saw as the last one.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/switch

Switch to another branch.

Path

sessionId

The session.

Body

ramo

The branch.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/branch-create

Create a branch.

Path

sessionId

The session.

Body

ramo

The new branch.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/branch-rename

Rename a branch.

Path

sessionId

The session.

Body

da

The current name.

a

The new name.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/branch-delete

Delete a branch. The first attempt refuses an unmerged branch and says so; forza: true deletes it anyway.

Path

sessionId

The session.

Body

ramo

The branch.

forza

true to delete it even if not merged.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/stash

Set the changes aside (stash).

Path

sessionId

The session.

Body

messaggio

A message for the stash.

conNuovi

true to include untracked files.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/stash-pop

Bring back a stash and drop it.

Path

sessionId

The session.

Body

indice

The stash’s position.

commit

The stash’s commit the window saw, so the right one is taken.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/stash-drop

Drop a stash.

Path

sessionId

The session.

Body

indice

The stash’s position.

commit

The stash’s commit the window saw.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/hunk

Stage, unstage or discard one hunk of a file’s diff (applied like GitHub Desktop, checked before it is applied: a hunk that does not apply changes nothing).

Only tracked text files: a new or binary file is staged whole (GIT_HUNK_UNSUPPORTED). If the file changed since the window read its diff, the hunk is refused (GIT_DIFF_CHANGED).

Path

sessionId

The session.

Body

percorso

The file.

area

lavoro (working tree) or preparato (staged).

indice

Which hunk of the diff.

impronta

The fingerprint of the diff the window saw.

azione

prepara (stage), togli (unstage) or annulla (discard).

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/commit-message

Ask the session’s model to write a commit message from the staged diff.

Path

sessionId

The session.

Body

bozza

A first line you already wrote, to keep.

lingua

en for English; Italian otherwise.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/fetch

Fetch from a remote.

Path

sessionId

The session.

Body

remoto

The remote (default: the branch’s own).

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/fetch-stop

Stop a fetch in progress.

Path

sessionId

The session.

Body

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/pull

Pull the current branch.

Path

sessionId

The session.

Body

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/push

Push the current branch.

Path

sessionId

The session.

Body

remoto

The remote (default: the branch’s own).

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/git/init

Create a Git repository in the session’s folder, on a main branch unless Git is configured otherwise.

Refused when the folder is already inside a repository. When the folder contains your user folder, it is refused until the request carries conferma: true.

Path

sessionId

The session.

Body

conferma

true to confirm a repository in a folder that contains your user folder.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
GIT_STORE_UNAVAILABLE	503	Git functions are not available on this server.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.