GitQL: SQL queries over your local .git files

What GitQL solves for people who read repository history

Git's own tooling answers questions one commit at a time. You get a log, you get a shortlog, you get blame. What you do not get is a grouped, ordered, aggregated view across the whole history without piping text through awk or writing a script. GitQL closes that gap by exposing the contents of a .git directory as relational tables and letting you query them with a SQL dialect. The README describes it as a tool built on the GitQL SDK that performs SQL-like queries on local .git files.

The audience is narrow but real. Release engineers who want to know which files churn most between tags. Maintainers who want commit counts per author without leaving the terminal. Anyone who has written the same shell pipeline three times and wants to stop. The README's own sample queries point at exactly these cases: counting commits per author, filtering refs by type, and summing insertions and removals per path.

It is not a Git replacement. It reads, it does not write. There is no query that creates a commit or moves a branch.

The engine, the parser and the six crates behind the binary

GitQL is a Rust workspace, and the Cargo.toml lists six member crates: gitql-core, gitql-std, gitql-ast, gitql-parser, gitql-engine and gitql-cli. That split is the architecture. The parser turns SQL text into an AST, the engine executes against a data provider, core holds the type and value system, and std supplies the standard library of functions. The CLI wires them together for the .git case.

The README calls the SDK an in-memory query engine implemented from scratch, with customization points for types, schema, data provider, operators and functions. That is the interesting part. The .git tool is one consumer of the SDK, not the whole product. The README lists four other tools built on it: LLQL for LLVM IR and bitcode, ClangQL for C and C++ source, FileQL for filesystem metadata, and PyQL for Python source files. Each one supplies its own schema and provider.

For the GitQL binary itself, the data source is the local repository. The Cargo.toml shows gix 0.80.0 as the Git implementation dependency, with default features disabled. Tables visible in the README's samples include commits, branches, tags, refs and diffs_changes. Columns named in those samples include author_name, author_email, title, commit_count, is_head, name, path, insertions and removals. The README does not document the full column list for every table; it points to a tables page in the documentation site for that.

Installing GitQL and running a first aggregation

The README does not inline installation steps. It links to a setup page on the documentation site for install or build instructions, and the crate is published on crates.io under the name gitql, so Cargo is the path the project points at.

cargo install gitql

That installs the binary. The version in the repository manifest is 0.43.0, and the most recent release listed is 0.43.0 from 2026-03-09. Once the binary is on your PATH, run it from inside a repository, since it queries the .git files of the current directory.

The README's samples are the fastest way to see what a query looks like. Keywords are case-insensitive, as in SQL. This one groups commits by author and orders by the count:

SELECT author_name, COUNT(author_name) AS commit_num
FROM commits
GROUP BY author_name, author_email
ORDER BY commit_num DESC
LIMIT 10

You should see a table with one row per author and email pair, sorted so the busiest contributor is first, capped at ten rows. If the query returns nothing, you are probably not in a repository directory.

The sample that shows where GitQL goes beyond git log sums line changes per file:

SELECT path, count() AS changes_count, SUM(insertions) AS additions, SUM(removals) AS removes
FROM diffs_changes
GROUP BY path
ORDER BY changes_count DESC

That output ranks files by how often they changed, with total added and removed lines beside each path. It is the query people usually reach for when they want to find hot spots in a codebase.

Where GitQL is the wrong tool

The README does not document rollback, and that is not an oversight in the README so much as a statement about scope. GitQL is a read path. If your task is to rewrite history, revert a merge, or fix a bad commit, you need Git itself, and GitQL will not help.

The harder limitation is the data source. Everything runs against a local .git directory. There is no documented remote provider, so querying across a fleet of repositories means cloning them first and running the tool per checkout. For an organization with hundreds of repositories, that turns a query into a script that loops over directories, and at that point the ergonomic advantage over a shell pipeline shrinks.

There is also a schema question the README leaves open. The samples reference a diffs_changes table with insertions and removals columns, but the README does not explain how those are computed for merge commits or how expensive the computation is on a large history. The documentation site has a tables page; that is where the answer would live, and a reader should check it before building a report on top of that table.

Finally, GitQL is not a database. The README describes an in-memory engine. There is no persistence layer, no indexes you maintain, and no server. Each invocation parses and executes. For interactive exploration that is fine. For a scheduled job that queries a repository on every push, the cost is paid in full every time.

GitQL against git log and against the SDK it is built on

The obvious alternative is the Git CLI itself. git log --format and git shortlog answer the author-count question directly, and git log --numstat gives per-file line changes. The difference in approach is textual versus relational. Git emits a stream you filter with grep, awk and sort; GitQL declares the shape of the answer in one statement, with GROUP BY, HAVING, ORDER BY, LIMIT and OFFSET available as first-class clauses. If your question is 'top ten authors by commit count', both work and Git is already installed. If your question is 'files with more than fifty changes where total removals exceed total insertions', the SQL form is shorter and less error-prone.

The second alternative is the GitQL SDK itself. The README frames the SDK as the general product and the GitQL binary as one tool built with it, alongside LLQL, ClangQL, FileQL and PyQL. If your data is not a .git directory but you want the same query surface, the SDK is the intended path, and the README links separate documentation pages for customizing the schema, the data provider, the standard library, the type system and the value system, plus a page on assembling the components. That is a meaningfully different commitment from installing a CLI: you write Rust and you own the provider.

A third reference point is the in-memory database category in the topics list. The distinction is that GitQL's engine is purpose-built and extensible rather than general. It does not aim to be a drop-in SQL database for arbitrary datasets; it aims to be a query layer you can point at a schema you define.

Maintenance, releases and what the MIT licence lets you do

The repository is not archived, and the last push was on 2026-04-21. The release history shows 0.41.0 in October 2025, 0.42.0 in November 2025, and 0.43.0 in March 2026. The CHANGELOG.md and RELEASING.md files at the repository root indicate a documented release process rather than ad hoc tagging.

The workspace layout matters for upgrade cost. The six crates are versioned independently: in the repository manifest, gitql-core and gitql-std sit at 0.20.0, gitql-ast at 0.39.0, gitql-parser at 0.42.0, and gitql-engine and gitql-cli at 0.43.0. If you depend on the SDK crates rather than the binary, a pre-1.0 version on every one of them means minor bumps can carry breaking changes, and you should read the changelog per crate rather than assuming the top-level version covers you. If you only use the installed CLI, this is invisible.

Licensing is MIT, with the copyright line reading 2023 to 2025 Amr Hesham. That permits use, modification, distribution, sublicensing and sale, provided the copyright notice and permission notice are included. The software is provided without warranty. For a tool you install and run, the practical obligation is minimal. For the SDK, embedding it in a distributed product means carrying the notice. This is a description of the licence text, not legal advice; check with counsel if you are shipping it inside something proprietary.

Editorial conclusion

Adopt GitQL if you need repeatable, aggregatable answers from repository history and are comfortable reading a schema before writing queries. Skip it if you only need one-off log inspection, since git log and git shortlog already cover that with no install. Before relying on it, check which tables your build exposes and confirm the diffs_changes path, because that table is where per-file insertion and removal counts come from and the README does not document how it behaves on merge commits.

Frequently asked questions

Official sources

1. AmrDeveloper/GQL on GitHub
2. License: MIT
3. Project website
4. README
5. Releases