Gitlear

Gitlear Current Format Spec

Gitlear is a plain-file issue, project, and document format for Git repositories. The files are the source of truth. The CLI, GUI, and MCP server are conveniences over the same Markdown tree that a person or agent can edit directly.

There is no database, hidden registry, persisted counter, or workspace config file.

Workspace Layout

NAME.md
KEY-PREFIX.md
issues/
  todo/
    TAG.md
    <issue-id>.md
members/
  <username>.md
assets/
  linear/
    <source-id>/
      <filename>
projects/
  <project-id>/
    PROJECT.md
    issues/
      todo/
        TAG.md
        <issue-id>.md
    docs/
      <doc-name>.md
    assets/
      linear/
        <source-id>/
          <filename>

Root issues/ is the workspace inbox. Project-owned issues live under the project directory. Project-owned docs also live under the project directory. assets/ directories are for non-entity binary or text files referenced from Markdown bodies. Tools must not treat files under assets/ as issues, projects, or docs. Members live at the workspace root because their handles are workspace-wide.

Reserved system filenames are exact uppercase: NAME.md, KEY-PREFIX.md, PROJECT.md, and TAG.md. Case-folded variants are invalid.

Root Metadata

NAME.md contains the workspace display name. KEY-PREFIX.md contains the key prefix used for generated issue/project keys and display keys. Tools read the first non-empty line from each file, stripping a leading Markdown heading marker when present.

Members

Path: members/<username>.md

---
name: Ada Lovelace
email: ada@example.com
github: ada-lovelace
---

The filename stem is the member username and the stable internal handle. Member frontmatter must not contain id.

Usernames are lowercase GitHub-style handles: ASCII a-z, 0-9, and hyphen, 1 to 39 characters, no leading or trailing hyphen, no consecutive hyphens, no .md suffix input, no path separators, no hidden names, no reserved Gitlear stems, no Windows device names, and no casefold duplicates.

Required member fields are name. Optional member fields are email and github. Store github without a leading @.

Issue assignee, issue/doc/project creator, project lead, and project members should store member handles without @ when a matching member exists:

assignee: ada
lead: ada
members:
  - ada

Human-facing UI may display @ada. Manual input may use ada or @ada. Historical free-form values such as ada@example.com or Ada <ada@example.com> remain readable. Tools resolve identity strings by handle first, then email case-insensitively, then GitHub username case-insensitively after stripping an optional @. If no member resolves, tools should preserve the raw string rather than blocking the write.

Status Directories

Issue status comes from the status directory:

Status slugs are lowercase kebab-case. CLI and API inputs may normalize spaces and underscores to hyphens. Default status dirs are todo, in-progress, in-review, done, and canceled. Any valid status dir is allowed, and tools may create custom status dirs on write. TAG.md inside a status dir is an optional Markdown label.

Issue frontmatter must not contain status or project.

Issues

---
id: EX-ISSUE0001
title: Write the current format spec
priority: high
assignee: ada
labels:
  - docs
number: 2
display_key: EX-2
creator: ada
created_at: 2026-06-24T09:00:00Z
updated_at: 2026-06-24T09:30:00Z
---
Markdown body goes here.

Required issue fields are id, title, created_at, and updated_at. id must match the filename stem and is globally unique across inbox and project issue dirs.

Optional issue fields include number, display_key, priority, assignee, parent, labels, creator, estimate, due_date, cycle, milestone, comments, relations, lifecycle, and extensions.

Move an issue between status dirs to change status. Move an issue between root issues/ and projects/<project-id>/issues/ to change project ownership.

Projects

Path: projects/<project-id>/PROJECT.md

Required project fields are id, name, status, created_at, and updated_at. id must match the project directory name. Project status values are backlog, planned, active, paused, completed, and canceled. Optional project fields include number, display_key, lead, start_date, target_date, priority, color, icon, summary, members, labels, milestones, initiative, health, updates, resources, creator, lifecycle, and extensions. Project lead, members, creator, and update authors should use member handles when possible.

Creating a project also creates projects/<project-id>/issues/ with default status dirs and TAG.md labels.

Documents

Path: projects/<project-id>/docs/<doc-name>.md

The document name is the filename stem. It is the document identity. Document frontmatter must not contain id or project.

---
title: Philosophy
issue: EX-ISSUE0001
number: 1
display_key: EX-D-1
creator: ada
created_at: 2026-06-24T08:15:00Z
updated_at: 2026-06-24T08:45:00Z
---
Document body goes here.

Required document fields are title, created_at, and updated_at. Optional document fields are number, display_key, issue, creator, and extensions.

Doc names may contain spaces, case, and punctuation, but must be safe as a single filename stem: no separators, empty names, ./.., hidden names, control characters, Windows-illegal characters or device names, trailing dots or spaces, reserved Gitlear stems, or casefold duplicates inside the same project. Duplicate doc names are allowed across different projects; unqualified lookup is ambiguous when more than one project has the same doc name.

Tool Extensions and Linear Imports

Entity frontmatter may include extensions, a map reserved for tool-specific metadata. Tools should preserve namespaces they do not own.

The Linear importer stores source metadata under extensions.linear. Imported issues, projects, and docs include at least kind and id; when available they also include the Linear URL, source metadata, attachment records, and local asset paths. Safe re-runs match existing files by extensions.linear.id.

When Linear exposes users, the importer writes matching workspace members under members/. It can create members from Linear names, emails, and GitHub usernames, fill missing email or GitHub metadata on one clear local match, and skip ambiguous matches instead of choosing between existing members.

Linear comments imported into the current comment format include a hidden Markdown marker of the form <!-- linear-comment-id:<id> --> so re-runs can avoid duplicate comments without adding top-level comment metadata.

Downloaded Linear files live under assets/linear/<source-id>/ for root inbox items or projects/<project-id>/assets/linear/<source-id>/ for project-owned items. Markdown bodies should link to the downloaded file and keep the original URL and checksum in extensions.linear.

Git Repository Workflow

A Gitlear workspace is intended to be a Git repository. Tools may initialize Git at the workspace root, add a remote named origin, commit the Markdown tree, and push with upstream tracking.

After copying data from Linear, the recommended CLI workflow is:

gitlear import linear --path ./workspace --name "Workspace" --prefix WS
cd ./workspace
gitlear repo link --remote git@github.com:owner/workspace.git

The equivalent manual workflow is:

cd ./workspace
git init -b main
git remote add origin git@github.com:owner/workspace.git
git add -A
git commit -m "gitlear: import Linear workspace"
git push -u origin main

When linking an existing workspace repository, tools should reuse the current branch and existing matching origin. They should not replace a different origin without explicit user confirmation. A workspace nested inside an unrelated parent source-code repository should not be linked as a workspace repo unless the user first opens or moves the actual workspace root.

Numbering

number and display_key are convenience fields. There is no persisted counter file. Tools assign a new number by scanning existing entities of the same kind and using max existing number plus one.

Recommended display key shapes:

Manual Editing Rules

Diagnostics

Tools should error on missing root metadata, invalid reserved filename casing, invalid status dirs, invalid doc names, invalid member usernames, flat issue files, root docs/, duplicate issue IDs, duplicate member handles, duplicate non-empty member emails or GitHub usernames, stale path-derived frontmatter fields, malformed YAML, unknown member frontmatter fields, and broken issue/doc links.

Tools should warn on unknown top-level frontmatter fields, duplicate display_key values, unresolved member-like identity strings, and relevant dirty or unpushed Git state.

Examples

See docs/spec/examples/ for a complete miniature workspace tree.