shad-go/gitfame/README.md

## gitfame

В этом задании нужно реализовать консольную утилиту для подсчёта статистик авторов git репозитория.

### Статистики

* Количество строк
* Количество коммитов
* Количество файлов

Все статистики считаются для состояния репозитория на момент конкретного коммита.

#### Расчёт

Каждой строке интересующего подмножества файлов репозитория сопоставляется последний коммит, модифицировавший эту строку.
Пустым файлам сопоставляются последние менявшие их коммиты.

После этого для каждого уникального автора, получившегося множества коммитов,
считается количество строк, уникальных коммитов и файлов, которые затрагивали коммиты автора.

Нужную информацию можно получить с помощью команды `git blame`:

```
✗ git blame utf8/README.md
f4640df4 (Fedor Korotkiy 2020-02-26 20:28:52 +0000 1) # utf8*
f4640df4 (Fedor Korotkiy 2020-02-26 20:28:52 +0000 2) 
f4640df4 (Fedor Korotkiy 2020-02-26 20:28:52 +0000 3) Задача объединяет несколько задач на строки и unicode.
f4640df4 (Fedor Korotkiy 2020-02-26 20:28:52 +0000 4) 
f4640df4 (Fedor Korotkiy 2020-02-26 20:28:52 +0000 5) Задача считается решённой, если все подзадачи решены.
```

`git blame` с флагом `--porcelain` (см. `git blame --help`) возвращает информацию в машиночитаемом формате.
Кроме того, этот формат схлопывает соседние строки относящиеся к одному коммиту,
что может сильно сократить размер результата. Поэтому использовать нужно его.

### Флаги

Утилита должна поддерживать следующий набор флагов:

**--repository** — путь до Git репозитория; по умолчанию текущая директория

**--revision** — указатель на коммит; HEAD по умолчанию

**--order-by** — ключ сортировки результатов, один из `lines` (дефолт), `commits`, `files`.

По умолчанию результаты сортируются по убыванию ключа `(lines, commits, files)`.
При равенстве ключей выше будет автор с лексикографически меньшим именем.
При использовании флага соответствующей поле в ключе перемещается на первое место.

**--use-committer** — булев флаг, заменяющий в расчётах автора (дефолт) на коммиттера

**--format** — формат вывода; один из `tabular` (дефолт), `csv`, `json`, `json-lines`;

`tabular`:
```
Name         Lines Commits Files
Joe Tsai     64    3       2
Ross Light   2     1       1
ferhat elmas 1     1       1
```
Human-readable формат. Для паддинга используется пробел.
см. [text/tabwriter](https://golang.org/pkg/text/tabwriter/).

`csv`:
```
Name,Lines,Commits,Files
Joe Tsai,64,3,2
Ross Light,2,1,1
ferhat elmas,1,1,1
```

`json`:
```
[{"name":"Joe Tsai","lines":64,"commits":3,"files":2},{"name":"Ross Light","lines":2,"commits":1,"files":1},{"name":"ferhat elmas","lines":1,"commits":1,"files":1}]
```

`json-lines`:
```
{"name":"Joe Tsai","lines":64,"commits":3,"files":2}
{"name":"Ross Light","lines":2,"commits":1,"files":1}
{"name":"ferhat elmas","lines":1,"commits":1,"files":1}
```

**--extensions** — список расширений, сужающий список файлов в расчёте; множество ограничений разделяется запятыми, например, `'.go,.md'`

**--languages** — список языков (программирования, разметки и др.), сужающий список файлов в расчёте; множество ограничений разделяется запятыми например `'go,markdown'`

Принадлежность файла к языку программирования определяется с помощью его расширения.
В [configs/language_extensions.json](configs/language_extensions.json) лежит маппинг.
Неизвестные языки никаких ограничений не накладывают. При их использовании можно написать warning в stderr.

**--exclude** — набор [Glob](https://en.wikipedia.org/wiki/Glob_(programming)) паттернов, исключающих файлы из расчёта

**--restrict-to** — набор Glob паттернов, исключающий все файлы, не удовлетворяющие ни одному из паттерну из набора

### Тесты

В [/tests/integration/testdata/bundles](test/integration/testdata/bundles) лежат запакованные git репозитории.
Каждый интеграционный тест ссылается на какой-нибудь бандл.

Как создать bundle? Находясь в git репозитории выполнить
```
git bundle create my.bundle --all
```

Как распаковать bundle? Находясь в пустой директории.
```
git clone /path/to/my.bundle .
```

### Ненавязчивые предложения

#### Project layout

В go есть [набор рекомендаций](https://github.com/golang-standards/project-layout) по организации структуры проекта.
И подпроект этого задания уже частично ему следует. Например, `main.go`, который вам нужно реализовать, лежит в [cmd/gitfame](./cmd/gitfame),
интеграционные тесты в `/test`.

В небольших проектах нет ничего плохого в том, чтобы весь код лежал плоско в корне.
Здесь же, для ознакомления предлагаем изучить общепринятый подход.

#### Cli

Можно познакомиться с [spf13/cobra](https://github.com/spf13/cobra),
популярной библиотекой для написания [cli](https://en.wikipedia.org/wiki/Command-line_interface).
В этой задаче cobra поможет распарсить аргументы, написать подробный help message, сделать алиасы для флагов.

### Git ликбез

Вся информация взята из [книги](https://github.com/pluralsight/git-internals-pdf/releases/download/v2.0/peepcode-git.pdf).

Смело советуем прочитать её всем, даже если в контексте задания вы знаете про Git достаточно.

---------

Объекты Git хранятся в специальной базе данных `Git Object Database` в директории .git.
В базе в сжатом виде хранятся объекты разных типов.
У каждого объекта есть SHA-1 хэш, а также небольшой header.

Несколько основных типов объектов:
* **blob** — соответствует файлу; хранит его данные (только содержимое)
* **tree** — соответствует директории; хранит список блобов и деревьев, а также их описание (имена файлов, типы, права доступа)
* **commit** — соответствует истории изменения дерева; хранит указатель на дерево, автора изменений, субъекта, добавившего изменения (committer), сообщение с описанием изменений, ссылку на предыдущие (родительские) коммиты

**branch** (ветка) — это не объект `Git Object Database`, а всего лишь файл в директории `.git/refs/heads/` с хэшом последнего для этой ветки коммита.
То есть ветка — это указатель на коммит.

**head** — это ссылка на коммит. В каждом репозитории по умолчанию есть **head** именем **master**.

**HEAD** — один выделенный **head**. Файл `.git/HEAD`. Родитель следующего коммита.

**HEAD** может ссылаться на коммит напрямую (**detached HEAD**).
Следующий коммит в таком случае не будет принадлежать никакой ветке.

Гораздо чаще **HEAD** ссылается на ветку.
В таком случае следующий коммит "попадёт" в ту же ветку и продвинет **HEAD**.
**HEAD** определяет текущую активную ветку.

**revision** (ревизия) — способ сослаться на Git объект.
Например, SHA-1 коммита — это ревизия на коммит,
`HEAD@{5 minutes ago}` — это ревизия на последний коммит на момент 5 минут назад,
`HEAD:README` — это ревизия на блоб.

### Критерии сдачи

Решение должно проходить все тесты, так же как и в обычной задаче.