https://github.com/thehale/git-authorship
Interactive reports to explore who wrote each line of code in a git repository.
https://github.com/thehale/git-authorship
copyright education git git-blame grading hacktoberfest oss-compliance reporting spdx
Last synced: 2 months ago
JSON representation
Interactive reports to explore who wrote each line of code in a git repository.
- Host: GitHub
- URL: https://github.com/thehale/git-authorship
- Owner: thehale
- License: mpl-2.0
- Created: 2022-08-30T19:18:57.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2025-05-26T10:04:37.000Z (5 months ago)
- Last Synced: 2025-07-23T00:26:56.539Z (3 months ago)
- Topics: copyright, education, git, git-blame, grading, hacktoberfest, oss-compliance, reporting, spdx
- Language: Python
- Homepage: https://jhale.dev/posts/git-authorship/
- Size: 25.1 MB
- Stars: 28
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Git-Authorship
Interactive reports showing who wrote each line of code in your git repository.
[](https://github.com/thehale/git-authorship/blob/master/LICENSE)
[](https://github.com/sponsors/thehale)
[](https://jhale.dev)
[](https://www.linkedin.com/comm/mynetwork/discovery-see-all?usecase=PEOPLE_FOLLOWS&followMember=thehale)
```bash
pip install git-authorship
git-authorship https://github.com/USERNAME/REPOSITORY
# Open build/authorship.html in a web browser
```
## Why?
Copyright is a thing, and whoever wrote the code in your repository holds an
exclusive copyright over it unless an agreement has been made otherwise.
While `git-authorship` does not help with managing copyright agreements from
contributors (see
[cla-assistant](https://github.com/cla-assistant/cla-assistant) and its
corresponding [GitHub
Action](https://github.com/contributor-assistant/github-action) for that
functionality), it does help you clearly identify who your contributors are and
the exact lines of code they wrote.
To support libraries undergoing re-licensing, `git-authorship` includes config
files for labelling the licenses under which contributors have shared their code.
## Other Features
### Mailmaps
When an author changes his/her commit name or email, that author will appear
multiple times in the authorship report.
To reduce that noise, add [a standard `.mailmap`
file](https://git-scm.com/docs/git-blame/2.15.4#_mapping_authors) to the root of
your git repository.
_.mailmap_
```
Proper Name
Proper Name
Proper Name Commit Name
```
### Ignore Revs
Automated tools (e.g. linters/formatters) which change many lines can lead to
authorship being attributed to the individual who ran the tool instead of the
original author.
However, if you identify the formatting commits and list their full commit SHAs
in a file, Git Authorship can correctly attribute the original author. The
default file is `.git-blame-ignore-revs`, placed at the root of the repository.
_.git-blame-ignore-revs_
```
# Run automated formatter
9c6927b59791eb71cce0a84d8c88fa14d5235fa8
# Run automated linter
ba09bf70676fb13891d15236951450b2f1aa9f3b
```
You can specify an alternate location via the `--ignore-revs-file` option
(resolved relative to the repository root).
```bash
git-authorship REPO_URL --ignore-revs-file .nonstandard-ignore-revs-file
```
### Author Licenses
You can include OSS licensing information for each author via a `.csv` file.
The `author-name` will be matched to the values shown in the generated
authorship report.
_licensing.csv_
```
author-name,license-SPDX-id
```
A list of SPDX license identifiers can be found at [spdx.org/licenses](https://spdx.org/licenses)
Then tell the CLI about the authorship file (resolved relative to your current
working directory)
```bash
git-authorship REPO_URL --author-licenses licensing.csv
```
### Pseudonyms
If certain files are being attributed to an unexpected author (e.g. if a
contributor copied code from another project, the `blame` would show the
contributor instead of the original author), you can manually override the
`blame` and licensing information.
_pseudonyms.csv_
```
target-path,actual-author,license-SPDX-id
```
A list of SPDX license identifiers can be found at [spdx.org/licenses](https://spdx.org/licenses)
> [!NOTE]
> `target-path` can refer to either a specific file or an entire folder which will be attributed to `actual-author` under the named software license.
Then tell the CLI about the pseudonyms file (resolved relative to your current
working directory)
```bash
git-authorship REPO_URL --pseudonyms pseudonyms.csv
```
## License
Copyright (c) 2022-2024 Joseph Hale, All Rights Reserved
Provided under the terms of the [Mozilla Public License, version 2.0](./LICENSE)
What does the MPL-2.0 license allow/require?
### TL;DR
You can use files from this project in both open source and proprietary
applications, provided you include the above attribution. However, if
you modify any code in this project, or copy blocks of it into your own
code, you must publicly share the resulting files (note, not your whole
program) under the MPL-2.0. The best way to do this is via a Pull
Request back into this project.
If you have any other questions, you may also find Mozilla's [official
FAQ](https://www.mozilla.org/en-US/MPL/2.0/FAQ/) for the MPL-2.0 license
insightful.
If you dislike this license, you can contact me about negotiating a paid
contract with different terms.
**Disclaimer:** This TL;DR is just a summary. All legal questions
regarding usage of this project must be handled according to the
official terms specified in the `LICENSE` file.
### Why the MPL-2.0 license?
I believe that an open-source software license should ensure that code
can be used everywhere.
Strict copyleft licenses, like the GPL family of licenses, fail to
fulfill that vision because they only permit code to be used in other
GPL-licensed projects. Permissive licenses, like the MIT and Apache
licenses, allow code to be used everywhere but fail to prevent
proprietary or GPL-licensed projects from limiting access to any
improvements they make.
In contrast, the MPL-2.0 license allows code to be used in any software
project, while ensuring that any improvements remain available for
everyone.