gitlogstats 1.0.7__tar.gz → 1.0.9__tar.gz

{gitlogstats-1.0.7 → gitlogstats-1.0.9}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: gitlogstats
-Version: 1.0.7
+Version: 1.0.9
 Summary: Track developers' contributions to one or more git repositories within a particular time range.
-Project-URL: Homepage, https://github.com/bloombar/git-developer-contribution-analysis
-Project-URL: Repository, https://github.com/bloombar/git-developer-contribution-analysis.git
-Project-URL: Bug Tracker, https://github.com/bloombar/git-developer-contribution-analysis/issues
+Project-URL: Homepage, https://github.com/bloombar/gitlogstats
+Project-URL: Repository, https://github.com/bloombar/gitlogstats.git
+Project-URL: Bug Tracker, https://github.com/bloombar/gitlogstats/issues
 Author-email: Tobody Tothing <nobody.nothing@nowhere.com>
 License:                     GNU GENERAL PUBLIC LICENSE
                                Version 3, 29 June 2007
@@ -695,7 +695,7 @@ Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: twine; extra == 'dev'
 Description-Content-Type: text/markdown
 
-![build](https://github.com/bloombar/git-developer-contribution-analysis/actions/workflows/build.yaml/badge.svg)
+![build](https://github.com/bloombar/gitlogstats/actions/workflows/build.yaml/badge.svg)
 
 # Git Developer Contributions Analysis
 
@@ -707,6 +707,7 @@ This script calculates the following, for each developer in each repository:
 - number of **lines added**
 - number of **lines deleted**
 - number of **files changed**
+- number of **merges** into the analyzed branch
 
 The results can be formatted as `csv`, `json`, or `markdown`.
 
@@ -734,7 +735,7 @@ optional arguments:
                         Start date in mm/dd/yyyy format
   -e END, --end END     End date in mm/dd/yyyy format
   -x EXCLUSIONS, --exclusions EXCLUSIONS
-                        A comma-separated string of files to exclude, e.g. --excusions "foo.zip, *.jpg, *.json"
+                        A comma-separated list of files, patterns or directories to exclude, e.g. --exclusions "foo.zip, *.jpg, vendor". Replaces the default list; use "" to exclude nothing
   -f {csv,json,markdown}, --format {csv,json,markdown}
                         The format in which to output the results
   -b BRANCH, --branch BRANCH
@@ -754,7 +755,7 @@ The `-r` and `-rf` flags control whether the script looks at a single repository
 Output the contributions of all developers to a single repository:
 
 ```bash
-gitlogstats -r https://github.com/bloombar/git-developer-contribution-analysis.git
+gitlogstats -r https://github.com/bloombar/gitlogstats.git
 ```
 
 Output the contributions of all developers to a set of repositories stored in a file named `repos.txt`, one URL per line (see [example file](./repos.txt)). Blank lines and lines starting with `#` are ignored. The results for all repositories are combined into a single table:
@@ -770,7 +771,7 @@ By default, the statistics of all contributors are calculated. The `-u` flag can
 Output the contributions of only the contributor named `bloombar` to a single repository:
 
 ```bash
-gitlogstats -u bloombar -r https://github.com/bloombar/git-developer-contribution-analysis.git
+gitlogstats -u bloombar -r https://github.com/bloombar/gitlogstats.git
 ```
 
 The same, but to a batch of repositories listed in the `repos.txt` file:
@@ -786,7 +787,7 @@ By default, contributions from a year ago until today are analyzed. Use the `-s`
 Output the contributions to a single repository for a specific date range, inclusive.
 
 ```bash
-gitlogstats -s 11/15/2021 -e 12/15/2021 -r https://github.com/bloombar/git-developer-contribution-analysis.git
+gitlogstats -s 11/15/2021 -e 12/15/2021 -r https://github.com/bloombar/gitlogstats.git
 ```
 
 The same, but to a batch of repositories listed in the `repos.txt` file:
@@ -795,6 +796,24 @@ The same, but to a batch of repositories listed in the `repos.txt` file:
 gitlogstats -s 11/15/2021 -e 12/15/2021 -rf repos.txt
 ```
 
+### Excluding files
+
+By default, common generated and binary files are left out of the analysis: `package.json`, `package-lock.json`, `Pipfile`, `Pipfile.lock`, `requirements.txt`, `*.jpg`, `*.png`, `*.gif`, `*.svg`, `*.pdf`, `*.zip`, `*.gz`, `*.tar`, `*.csv` and `*.json`. Use `-x` to give your own comma-separated list instead. It replaces the default list rather than adding to it.
+
+Each item can be a file name, a glob pattern or a directory, and is matched in any directory of the repository. A directory name, such as `vendor` or `vendor/`, excludes everything inside it. A path such as `docs/*.md` matches only inside directories with that name.
+
+```
+gitlogstats -rf repos.txt -x "*.json, *.lock, vendor, docs/*.md"
+```
+
+Exclude nothing:
+
+```
+gitlogstats -rf repos.txt -x ""
+```
+
+Excluded files are left out of the commit, line and file counts. A commit that only touches excluded files is not counted at all. Exclusions do not affect the merge count.
+
 ### Filter Contributors
 
 By default, every contributor in a repository's history is listed, with zeros for those who were inactive in the date range. Use `-c` to show only contributors with activity.
@@ -816,7 +835,7 @@ gitlogstats -s 11/15/2021 -e 12/15/2021 -rf repos.txt -f markdown
 Flags can be combined to provide more targeted analysis, e.g. a specific contributor over a specific date range
 
 ```
-gitlogstats -u bloombar -s 11/15/2021 -e 12/15/2021 -r https://github.com/bloombar/git-developer-contribution-analysis.git -f json
+gitlogstats -u bloombar -s 11/15/2021 -e 12/15/2021 -r https://github.com/bloombar/gitlogstats.git -f json
 ```
 
 The same, but to a batch of repositories listed in the `repos.txt` file:
@@ -831,11 +850,21 @@ Use `-v` to print debugging information. It is written to standard error, so the
 
 ## How statistics are counted
 
-- **commits** — commits authored by the contributor in the date range, including merge commits. Commits that change no files, or only excluded files (`-x`), are not counted.
-- **insertions** / **deletions** — lines added and removed, as reported by `git log --shortstat`. Binary files and merge commits add no lines, so merged work is never counted twice.
+- **commits** — non-merge commits authored by the contributor in the date range. Commits that change no files, or only excluded files (`-x`), are not counted. Merge commits are counted under **merges** instead.
+- **insertions** / **deletions** — lines added and removed, as reported by `git log --shortstat`. Binary files add no lines, and merges add none either, so merged work is never counted twice.
 - **files** — the number of files each commit changed, summed over the contributor's commits.
+- **merges** — merge commits the contributor made directly on the analyzed branch in the date range. The author of a merge commit is the person who merged, so this covers merges made locally and pushed, and pull requests merged on GitHub, GitLab or Bitbucket with a merge commit.
+
+Some merges are not counted:
+
+- Merges that leave no merge commit: fast-forward merges, and pull requests merged with "Squash and merge" or "Rebase and merge". A squash commit counts as an ordinary commit by whoever made it.
+- Merges made inside another branch, such as merging `main` into a feature branch with `git pull` or GitHub's "Update branch" button. These keep a branch up to date rather than merge work into it.
+- Merges on other branches, unless that branch is analyzed with `-b`.
+- Local merges that were never pushed.
+
+A merge made on GitHub uses the person's GitHub profile name and email, which may differ from their local git settings. They can then appear under two names (see [Redundant usernames](#redundant-usernames)).
 
-Each commit is credited to its author's name, after applying the repository's `.mailmap` if it has one. Commit messages are never read, so statistics are the same whether messages are one line, many lines, or empty.
+Each commit is credited to its author's name, after applying the repository's `.mailmap` if it has one. Merges are credited the same way. Commit messages are never read, so statistics are the same whether messages are one line, many lines, or empty.
 
 ## Development