Managing Git repositories

This page covers creating repositories, understanding the naming rules, cloning and pushing over SSH, and the distinction between standalone repositories and the site stores that back Markdown sites.

Creating a repository

/git repo create my-project

Expected output:

  created repository 'my-project'
  owner: admin (*/git/my-project)

Two things happen immediately: the bare repository is created on disk, and the creating user is granted owner access on */git/my-project. That grant covers the repository across all frontends — SSH today, HTTP when it lands.

Naming rules

Repository names must be:

lowercase letters, digits, and hyphens only
not starting or ending with a hyphen

Valid examples: my-docs, api-reference, project1, config

Invalid examples: My-Docs (uppercase), api_reference (underscore), -project (leading hyphen), project.git (dot)

The rule exists because names appear in SSH URLs and are used as filesystem paths. Keeping them lowercase and hyphen-separated avoids case-sensitivity issues across operating systems and makes URLs predictable.

Listing repositories

/git repo list

Shows all repositories the current user can access, with their clone URLs:

  my-project                   ssh://admin@localhost:2222/my-project.git
  config                       ssh://admin@localhost:2222/config.git

This only shows repositories the user has at least reader access to. A repository that exists but has no grant for the current user does not appear here.

Cloning and pushing over SSH

Cloning

git clone ssh://admin@localhost:2222/my-project.git

The clone produces a normal local Git repository. Every standard Git operation works against it.

The SSH URL explained

ssh://admin@localhost:2222/my-project.git
      ─────  ─────────  ────  ────────── ────
      user   host       port  repo name  suffix

Component	Meaning
`admin`	The Everlock user authenticating over SSH. Use the actual username, not always `admin`.
`localhost`	The hostname of the Everlock instance. Replace with a real hostname for remote instances.
`2222`	The SSH port. Everlock's default is `2222`. Standard SSH port `22` needs no port in the URL.
`my-project`	The repository name, exactly as created with `/git create`.
`.git`	The bare-repository suffix — the same convention GitHub and GitLab use. Everlock advertises it and stores each repo on disk as `<name>.git`, but the server accepts the URL with or without it: `…/my-project` and `…/my-project.git` are equivalent.

On a remote public instance with a real hostname and the default port:

git clone ssh://alice@git.example.com:2222/my-project.git

If the Everlock SSH frontend is configured on port 22 (standard):

git clone ssh://alice@git.example.com/my-project.git
# or in SCP-style shorthand:
git clone alice@git.example.com:my-project.git

Pushing

cd my-project
git add .
git commit -m "initial commit"
git push

Everlock stores the incoming pack bundle directly — it does not unpack to loose objects. The push output follows standard Git protocol:

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Writing objects: 100% (5/5), 412 bytes | 412.00 KiB/s, done.
Total 5 (delta 0), reused 0 (delta 0), pack-reused 0
To ssh://admin@localhost:2222/my-project.git
 * [new branch]      main -> main

If the repository backs a site, the updated content is served immediately on the next HTTP request — there is no separate deploy step.

Standalone repositories vs site stores

Everlock has two kinds of repositories:

Site stores are created implicitly when you run /site create. Their name defaults to the site name. The site backend reads content directly from the repository's HEAD and serves it over HTTP. You do not create these with /git create.

Standalone repositories are created with /git create. They are plain bare Git repositories with no automatic connection to the HTTP site backend. Use them for anything that needs version control but is not a public-facing site: configuration files, shared scripts, documentation drafts, data exports, or anything else you want to manage through Git.

Both types behave identically from Git's perspective. The difference is solely whether a site backend entry exists that reads from that store.

Example: a config repository

/git create server-config

git clone ssh://admin@localhost:2222/server-config.git
cd server-config
echo "# Everlock deployment notes" > README.md
git add README.md
git commit -m "initial"
git push

Grant a colleague read access so they can clone it:

/users grant bob */git/server-config reader

Grant another colleague write access:

/users grant carol */git/server-config writer

See Access control for the full grant model.

Inspecting the repository on disk

Everlock stores repositories as standard bare Git repositories. Once you have a local clone, you can inspect the server-side state with normal tools:

# List refs on the remote
git ls-remote ssh://admin@localhost:2222/my-project.git

# Show log of what's on the server
git log origin/main

The repository on disk is also directly readable with git or gix if you have shell access to the server's data directory — Everlock uses no custom format.

Maintenance: pruning unreachable objects

Everlock stores every object loose. A crash mid-write — for example an out-of-memory kill during a push — or a rewound branch can leave unreachable objects behind: objects no ref points at, which nothing can ever read but which still take up space. The admin console can clean them up in-process, without the git CLI:

/git repo gc my-project

  gc 'my-project': 4120 reachable, pruned 37 unreachable object(s) (12.4 MiB)

The prune is conservative by design. An object is removed only when both are true:

it is unreachable from every ref (branches, tags, and pull-request refs), and
it is older than a one-hour grace window — so an in-flight push or commit that has written objects but not yet moved its ref cannot lose them.

If the repository is already damaged — missing an object a ref still needs — gc aborts and deletes nothing rather than risk making it worse. It never rewrites reachable history and never touches refs, so it is safe to run against a live repository. Running it requires write access to the repository.