gitstalk docs repositories

Repositories live

A repository holds your code, a bean branch for every change in flight, and its own checking engine. Create one, push a bean, and it is checked and landed with no other setup.

Create one

Open New repository from the + New menu in the header. Pick an owner (you, or an organization that lets you create repositories), a name, an optional description and a visibility, then choose how it starts.

Importing a private repository and two-way sync with another forge are planned.

From an agent, a script or a push

Three more ways create a repository, through the same path as the form, so the same names, owners and starters apply. Each needs the create scope: "may create repositories in namespaces where the person may create them". The setup script asks for it (the SSH key approval page shows it ticked), an agent's consent page offers it, and a token from Settings, Tokens can have it. A new repository is private and empty unless you ask otherwise.

curl -sS https://gitstalk.io/api/repos \
  -H "Authorization: Bearer $GITSTALK_TOKEN" -H 'content-type: application/json' \
  -d '{"name":"api","visibility":"private"}'

Every error body is {"error": {"code", "message"}}.

Push to create

Pushing to a missing owner/name.git creates it when your credential has create and the owner is you, or an organization whose members may create repositories. Push one branch: main, master, stalk or bean/<name>. That commit, with its history, becomes the first commit of the stalk; no bean is opened, because there was nothing to protect yet. From then on every push is an ordinary one: beans only, checked before they land.

git remote add origin https://gitstalk.io/you/api.git
git push origin HEAD:refs/heads/bean/start

• Without create, the push is refused with a hint: use repo_create, /new, or a credential with the scope.
• A name you renamed away from still leads to the renamed repository while its redirect exists, so the push goes there and nothing is created.
• A repository made empty by repo_create or the API holds a README until its first push, which then becomes its stalk, so an existing project keeps its history. Made empty on the web, the README stays and the first bean lands on it.

The start page

Until the first bean lands, the repository page has one job: show exactly how to begin. Everything is copyable.

Connect git: three ways

The Code button

Once something has grown, the repository page opens on the Code tab, and the start page gives way to a Code button at the right of the bar above the files, where GitHub puts it. It opens a panel with three tabs; the last one you used opens next time. On a phone the panel is a sheet from the bottom of the screen. Escape or a click outside closes it.

The file tree

The Code tab's left pane has two tabs, Stalk and Files. On a folder (the front page included) it shows the beanstalk: beans growing at the tip and landings down the line, each linking to its page in Changes. Open a file and it switches to the file tree; either tab is a click away, and opening a folder brings the stalk back.

In the Files tab a folder tree sits beside whatever you open, as in an editor: the tree on the left, the file (or the folder and its README) on the right, and the bar with the line or bean you are browsing across both. The tree opens down to the open file and highlights it, and a green line runs down the indent guides from the top folder to it. Opening a file keeps the tree as it was: the folders you opened stay open and the tree keeps its scroll. The address is always the file's own, so a link or a refresh opens the same place. Switching to the sprout or a bean switches both sides.

A tour of the tabs

Every repository has the same seven tabs. Everyone who may see the repository sees the tabs; the Settings tab shows for people with a role.

There is no separate Home or Stalk tab. The old Stalk address redirects to History. The pages work at night, by day and at phone width.

Reading History

Renamed and moved

live When a repository is renamed or moved to another owner (you to an organization, an organization to you, or between organizations), its old address keeps working, so existing clones, CI and agent setups do not break.

$ git push origin bean/first-change
remote: gitstalk: this repository moved to acme/payments; the old address keeps working.
remote: gitstalk: to use the new one: git remote set-url origin https://gitstalk.dev/acme/payments.git

• Renames chain: after a to b to c, both a and b lead to c. An old handle and an old name together still work.
• An old address stops redirecting once someone creates a repository with exactly that owner and name, as on GitHub. Deleting the repository removes its old addresses.
• An internal repository moved to a person becomes private, because only organizations have internal repositories.

Archive, transfer, delete

These live in Settings, Danger zone, which the owner sees. Each asks before it acts.

Renaming, the description and the social image are in Settings, where profile and upload details also live.

Good to know

• Storage is named by id, so renaming never moves git data.
• Teams are not built yet (planned). Give access person by person or through an organization.
• Organization handles cannot be changed yet.