CLI/API access to known repositories list + launch to Changes view
- Dominant language
- TypeScript
- Stars
- 21.8k
- Forks
- 10.5k
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 25
Description
### The feature request
Third-party tools that integrate with GitHub Desktop currently have no supported way to ask it two very basic questions, or to hand off to it cleanly:
1. **What repositories does GitHub Desktop know about, and where are they on disk?** The "Repository list" (Ctrl+T / Cmd+T) and each repository's local path exist only inside GitHub Desktop's own internal state.
2. **Which repository is currently selected?** Same problem — this is only visible in the app's own UI.
3. **Please show repository X's Changes tab (starting the app first if it isn't running).** The `github ` command-line helper (documented at
[https://docs.github.com/en/desktop/overview/launching-github-desktop-from-the-command-line](https://docs.github.com/en/desktop/overview/launching-github-desktop-from-the-command-line))
gets us partway — it will launch GitHub Desktop and add/select a
repository by path — but there's no equivalent for choosing which
tab is shown once it's open, and it's only available on Windows and
macOS.
The only way to approximate any of this today is to read GitHub
Desktop's own local repository database directly. That database is
built on Dexie/IndexedDB
(`app/src/lib/databases/repositories-database.ts`), backed by
Chromium's IndexedDB storage under Electron's `userData` directory.
That's an internal, undocumented, versioned binary format with no
supported read API — parsing it means reverse-engineering Chromium's
structured-clone encoding, and any integration built on it is liable
to break on a future GitHub Desktop release. (We know this because a
maintainer commented on a past Dexie-related crash report that the
team has considered moving away from IndexedDB entirely — see
https://github.com/desktop/desktop/issues, "we've been looking at
migrating away from IndexedDB down the track" — which would break any
such integration outright.)
We ran into this building a small Gramps (genealogy software) addon
that helps addon developers package and publish releases: after
generating output files in a local clone, the addon wants to hand off
to GitHub Desktop so the developer can review and commit the changes.
Today the addon can only guess at repository names/paths by scanning
common developer folders for `.git` directories — a poor, easily wrong
substitute for asking GitHub Desktop directly.
### Proposed solution
A small, explicitly read-only, local surface for querying the information above — it doesn't need to be a network-facing API. Any of the following mechanisms would work for us; we'd defer to whichever fits GitHub Desktop's architecture best:
• **A CLI subcommand**, e.g. github --list-repositories /
github --list-repositories --json, printing each known
repository's name and local path, with the currently-selected one
flagged (e.g. "active": true in JSON output).
• **A local IPC/JSON-RPC socket or named pipe** that a companion
process could query for the same data, for tools that want to avoid
spawning a CLI process per query.
• **A documented, stable export file** (e.g. a small JSON file written
to a known location under GitHub Desktop's `userData` directory,
refreshed whenever the repository list or selection changes) that
external tools can read without touching the Dexie/IndexedDB store
directly.
Whichever shape it takes, we'd like it to expose, per known repository:
• `name` — the display name shown in the Repository list.
• `path` — the local filesystem path GitHub Desktop has associated
with it.
• Which one (if any) is currently selected/active.
And separately, a supported way to say
**"show repository X's Changes tab, starting GitHub Desktop first if it isn't already running"**
— for example github --show-changes , or a path + view=changes
parameter added to the existing github launch mechanism. This
would also close the Windows/macOS-only gap in today's github
helper if it's extended in a way that Linux builds can adopt too
(acknowledging Linux isn't an officially supported platform for GitHub
Desktop itself, but the shiftkey/desktop community build follows the
same launch conventions).
To be clear about scope: we are not asking for anything related to diffing, git status, or deciding what counts as a "change" — that analysis should stay entirely inside GitHub Desktop. We only want to know what it already knows (names, paths, current selection) and to ask it to bring a specific repository's Changes view forward.
## Alternatives we've considered:
• **Parsing the Dexie/IndexedDB store directly**. Rejected: undocumented,
versioned binary format; no supported read API; confirmed fragile by
the team's own stated interest in moving off IndexedDB.
• **Scanning the filesystem for .git folders under common developer
directories** (e.g. ~/Documents/GitHub, ~/repos, etc.) as a proxy
for the repository list. This is what our addon does today. It works
passably for "list of local git clones" but can't tell us which one
GitHub Desktop considers active, can find false positives (git
clones GitHub Desktop was never told about), and can miss
repositories cloned somewhere non-standard.
• **OS-level UI automation** (sending Ctrl+1/Cmd+1 via xdotool,
osascript, or PowerShell's SendKeys after activating the GitHub
Desktop window) to reach the Changes tab. We prototyped this and it
technically works when the automation tool is available, but it's
fragile (breaks under Wayland, depends on window titles/process
names that could change), and it's the kind of thing that shouldn't
be necessary for a first-party integration point.
### Additional context
• Existing docs this request builds on:
• Launching from the command line:
[`https://docs.github.com/en/desktop/overview/launching-github-desktop-from-the-command-line`](https://docs.github.com/en/desktop/overview/launching-github-desktop-from-the-command-line)
• Keyboard shortcuts (Ctrl+1/Cmd+1 for Changes, Ctrl+T/Cmd+T for the
Repository list):
https://docs.github.com/en/desktop/overview/github-desktop-keyboard-shortcuts
• Repository database implementation referenced above:
`app/src/lib/databases/repositories-database.ts`
• Our specific use case is a Gramps addon (desktop GTK app, Python), so a CLI or file-based mechanism is easier for us to consume than anything browser/JS-oriented, but we don't have a strong preference beyond "documented, stable, and read-only."
• Happy to test against a pre-release build if this is something the team would consider prototyping.
Contributor guide
Research direction
Start with app/src/lib/databases/repositories-database.ts and the existing github command-line launch flow described in the linked documentation. Compare the proposed CLI, IPC, and export-file approaches against the app architecture before choosing one. Done means a documented, stable read-only way to list repository names, paths, and active selection, plus a way to open a repository's Changes view.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- electron, git, github, typescript
- Domain
- api, cli, desktop, developer-experience
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100