Skip to content

Update README #110

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Feb 10, 2017
88 changes: 60 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,18 @@
# ![gitql](https://rawgit.com/gitql/gitql/master/gitql-logo.svg)

[![Build Status](https://travis-ci.org/gitql/gitql.svg?branch=master)](https://travis-ci.org/gitql/gitql) [![codecov](https://codecov.io/gh/gitql/gitql/branch/master/graph/badge.svg)](https://codecov.io/gh/gitql/gitql) [![GoDoc](https://godoc.org/github.com/gitql/gitql?status.svg)](https://godoc.org/github.com/gitql/gitql)

**gitql** is a SQL interface to Git repositories, written in Go.

**WARNING: gitql is still in a very early stage of development. It is considered experimental.**
<p align="center">
<img src="https://rawgit.com/gitql/gitql/master/gitql-logo.svg">
</p>

<p align="center">
<a href="https://codebeat.co/projects/gb.xjqchip.workers.dev-gitql-gitql"><img alt="codebeat badge" src="https://codebeat.co/badges/ff0a63ef-e1b1-4a8a-9662-8b2ae17718fa" /></a>

<a href="https://travis-ci.org/gitql/gitql"><img alt="Build Status" src="https://travis-ci.org/gitql/gitql.svg?branch=master" /></a>

<a href="https://codecov.io/gh/gitql/gitql"><img alt="codecov" src="https://codecov.io/gh/gitql/gitql/branch/master/graph/badge.svg" /></a>

<a href="https://godoc.org/github.com/gitql/gitql"><img alt="GoDoc" src="https://godoc.org/github.com/gitql/gitql?status.svg" /></a>
</p>

<a href="https://asciinema.org/a/102733?autoplay=1" target="_blank"><img src="https://asciinema.org/a/102733.png" width="979"/></a>

## Installation

Expand All @@ -13,15 +21,16 @@ the gitql binary.

## Usage

```
```bash
Usage:
gitql [OPTIONS] <query | version>
gitql [OPTIONS] <query | shell | version>

Help Options:
-h, --help Show this help message

Available commands:
query Execute a SQL query a repository.
shell Start an interactive session.
version Show the version information.
```

Expand All @@ -31,35 +40,58 @@ For example:
$ cd my_git_repo
$ gitql query 'SELECT hash, author_email, author_name FROM commits LIMIT 2;'
SELECT hash, author_email, author_name FROM commits LIMIT 2;
+------------------------------------------+--------------------+---------------+
| HASH | AUTHOR EMAIL | AUTHOR NAME |
+------------------------------------------+--------------------+---------------+
| 02e0aa0ef807d2ae4d02ecdbe37681db9e812544 | Santiago M. Mola | [email protected] |
| 034cb63f77f4a0d30d26dabb999d348be6640df7 | Antonio J. Navarro | [email protected] |
+------------------------------------------+--------------------+---------------+
+------------------------------------------+---------------------+-----------------------+
| HASH | AUTHOR EMAIL | AUTHOR NAME |
+------------------------------------------+---------------------+-----------------------+
| 003dc36e0067b25333cb5d3a5ccc31fd028a1c83 | [email protected] | Santiago M. Mola |
| 01ace9e4d144aaeb50eb630fed993375609bcf55 | [email protected] | Antonio Navarro Perez |
+------------------------------------------+---------------------+-----------------------+
```

You can use the interactive shell like you usually do to explore tables in postgreSQL per example:

```bash
$ gitql shell

gitQL SHELL
-----------
You must end your queries with ';'

!> SELECT hash, author_email, author_name FROM commits LIMIT 2;

--> Executing query: SELECT hash, author_email, author_name FROM commits LIMIT 2;

+------------------------------------------+---------------------+-----------------------+
| HASH | AUTHOR EMAIL | AUTHOR NAME |
+------------------------------------------+---------------------+-----------------------+
| 003dc36e0067b25333cb5d3a5ccc31fd028a1c83 | [email protected] | Santiago M. Mola |
| 01ace9e4d144aaeb50eb630fed993375609bcf55 | [email protected] | Antonio Navarro Perez |
+------------------------------------------+---------------------+-----------------------+
!>
```

## Tables

gitql exposes the following tables:

* commits (hash, author_name, author_email, author_time, comitter_name, comitter_email, comitter_time, message)
* blobs (hash, size)
* references (hash, name, is_branch, is_note, is_remote, is_tag, target)
* tags (hash, name, tagger_email, tagger_name, tagger_when, message, target)
* tree_entries (tree_hash, entry_hash, mode, name)
| Name | Columns |
|:------------:|:---------------------------------------------------------------------------------------------------:|
| commits | hash, author_name, author_email, author_time, comitter_name, comitter_email, comitter_time, message |
| blobs | hash, size |
| references | hash,hash, name, is_branch, is_note, is_remote, is_tag, target |
| tags | hash, name, tagger_email, tagger_name, tagger_when, message, target |
| tree_entries | tree_hash, entry_hash, mode, name |

## SQL syntax

gitql supports a subset of the SQL standard, currently including:
We are continuously adding more functionality to gitql. We support a subset of the SQL standard, currently including:

* `SELECT`
* `WHERE`
* `ORDER BY` (with `ASC` and `DESC`)
* `LIMIT`
* `GROUP BY` (with `COUNT` and `FIRST`)
* `SHOW TABLES`
* `DESCRIBE TABLE`
| | Supported |
|:----------------------:|:---------------------------------------------------------------------------------:|
| Comparison expressions | !=, ==, >, <, >=,<= |
| Grouping expressions | COUNT, FIRST |
| Standard expressions | ALIAS, LITERAL, STAR (*) |
| Statements | CROSS JOIN, DESCRIBE, FILTER (WHERE), GROUP BY, LIMIT, SELECT, SHOW TABLES, SORT |

## License

Expand Down