The GQL introduced here is not the more widely known GraphQL, but an abbreviation for Git Query Language.
GQL allows us to use SQL syntax to query Git repositories, thereby quickly obtaining various information about them, such as statistics on the number of commits by all authors in a repository.
1. Installation and Usage
Download the latest version from GitHub to a folder in your local PATH, then rename it to gql to execute it directly.
2. First Use
In the command line, change the directory to your Git working directory. First, use -h to view command-line options; if no options are provided, it enters interactive mode:
gql -h
GitQL is an SQL-like query language to run on local repositories.
Usage: gitql [OPTIONS]
Options:
-r, --repos <REPOS> Path for local repositories to run query on
-s, --script <file> Script file containing one or more queries
-q, --query <GitQL Query> GitQL query to run on selected repositories
-p, --pagination Enable printing results with pagination
-ps, --pagesize Set pagination page size [default: 10]
-o, --output Set output format [render, json, csv]
-a, --analysis Print query analysis
-e, --editor Enable GitQL Rich Line Editor
-h, --help Print GitQL help
-v, --version Print GitQL current version
3. Key Usage Points
- Use
show tablesto query available tables. There are 6 tables: commits, branches, refs, diff_changes, tags, and diffs.
c:/git/obsidian-translations[master] # gql
gitql > show tables
╭───────────────╮
│ Tables │
╞═══════════════╡
│ commits │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ branches │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ refs │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ diffs_changes │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ tags │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ diffs │
╰───────────────╯
gitql >
- List table column structure:
describe
gitql > describe commits
╭─────────────────┬──────────╮
│ Field ┆ Type │
╞═════════════════╪══════════╡
│ commit_id ┆ Text │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┤
│ title ┆ Text │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┤
│ message ┆ Text │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┤
│ author_name ┆ Text │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┤
│ author_email ┆ Text │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┤
│ committer_name ┆ Text │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┤
│ committer_email ┆ Text │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┤
│ datetime ┆ DateTime │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┤
│ parents_count ┆ Int │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┤
│ repo ┆ Text │
╰─────────────────┴──────────╯
- Find branches after
2025-01-01
select * from branches where updated >= '2025-01-01 12:00:00' order by updated
- Find commit information after
2025-03-01
select title, datetime from commits where datetime >= '2025-03-01 00:00:00' order by datetime
- Commit count statistics by committer (top 10 committers by 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
- Find this year's commit information for a specific committer
SELECT title,author_name,datetime FROM commits WHERE LOWER(author_name) = "emisjerry" and datetime>='2025-01-01 00:00:00'
- Find committers and their commit counts for commits containing a specific string in the repository
select author_name,count(author_name) as Count from commits where message like '%zh_TW%' group by author_name
4. 💡 Related Links
💡 Explanatory article (Traditional Chinese): https://jdev.tw/blog/8805/
💡 Explanation article(English): https://quaily.com/jdevtw-en/p/git-query-language-exploring-git-repository-command-line-tool
💡 解説記事(日本語): https://quaily.com/jdevtw-jp/p/git-query-language-exploring-git-repository-command-line-tool
✅GitHub: https://github.com/AmrDeveloper/GQL
✅Official Documentation: https://amrdeveloper.github.io/GQL/
✅Another GitQL GitHub: https://github.com/filhodanuvem/gitql