Add SLOC analysis and composition table (analyzesloc + SLOC helpers) — gitstats

Track and plot pace of changes (pace_of_changes data + pace_of_changes.png/.dat) — gitstats
Add PDF report generator using fpdf2 with embedded charts (PDFReportCreator) — gitstats
Add repository size calculation and getter (repository_size_mb + getRepositorySize) — gitstats
Add last-30-days and last-12-months activity summaries and accessors (last_30_days_*, last_12_months_*) — gitstats
Add SLOC-per-extension breakdown on lines page and related data writers — gitstats
Add commit timing / external-command timing and --debug/--verbose tracing in runner — gitstats
Chores

Update README with usage, options, dependencies, outputs, and troubleshooting — README.md
Replace counting patterns with defaultdict(int) for robustness (DataCollector fields) — gitstats
Fix multirepo tags isolation (ensure tags cleared/isolated per repo) — gitstats
Initialize author entries consistently to avoid KeyError (author info structure) — gitstats
Generate and keep consistent .dat/.plot gnuplot artifacts and improve createGraphs hygiene — gitstats

Makefile

@@ -1,34 +0,0 @@
-PREFIX=/usr/local
-BINDIR=$(PREFIX)/bin
-RESOURCEDIR=$(PREFIX)/share/gitstats
-RESOURCES=gitstats.css sortable.js *.gif
-BINARIES=gitstats
-VERSION=$(shell git describe 2>/dev/null || git rev-parse --short HEAD 2>/dev/null || date +%Y-%m-%d)
-SEDVERSION=perl -pi -e 's/VERSION = 0/VERSION = "$(VERSION)"/' --
-
-all: help
-
-help:
-	@echo "Usage:"
-	@echo
-	@echo "make install                   # install to ${PREFIX}"
-	@echo "make install PREFIX=~          # install to ~"
-	@echo "make release [VERSION=foo]     # make a release tarball"
-	@echo
-
-install:
-	install -d $(BINDIR) $(RESOURCEDIR)
-	install -v $(BINARIES) $(BINDIR)
-	install -v -m 644 $(RESOURCES) $(RESOURCEDIR)
-	$(SEDVERSION) $(BINDIR)/gitstats
-
-release:
-	@cp gitstats gitstats.tmp
-	@$(SEDVERSION) gitstats.tmp
-	@tar --owner=0 --group=0 --transform 's!^!gitstats/!' --transform 's!gitstats.tmp!gitstats!' -zcf gitstats-$(VERSION).tar.gz gitstats.tmp $(RESOURCES) doc/ Makefile
-	@$(RM) gitstats.tmp
-
-man:
-	pod2man --center "User Commands" -r $(VERSION) doc/gitstats.pod > doc/gitstats.1
-
-.PHONY: all help install release

README.md

@@ -44,15 +44,56 @@ Example:
 
 ```sh
 python gitstats /path/to/your/repo /path/to/output
+To generate statistics for a git repository:
+
+```sh
+python gitstats <path-to-git-repo> <output-directory>
+```
+
+Common options:
+
+- `--debug`: print detailed command traces and timings (useful for diagnosing issues).
+- `--verbose`: show progress and executed git/gnuplot commands.
+- `--processes N`: run N worker processes when collecting data (default depends on your machine).
+
+Example:
+
+```sh
+python gitstats /path/to/your/repo /path/to/output --verbose --processes 4
 ```
 
-This will analyze the git repository and generate an HTML report in the output directory.
+This will analyze the git repository and generate an HTML report (and optional PDF) in the output directory.
+
+Required system dependencies and notes:
+
+- **Python 3.x**: the script targets modern Python 3.
+- **Git**: required for reading repository history.
+- **gnuplot**: used to render charts. If not installed, `.dat` and `.plot` files will still be produced but PNG graphs won't be generated.
+- **fpdf** (Python package): used to create a summary PDF. You may see deprecation warnings from older fpdf APIs; the PDF is still created successfully, but updating `fpdf` usage can remove warnings.
+
+Install Python dependencies (if provided):
+
+```sh
+pip install -r requirements.txt
+```
+
+On Debian/Ubuntu you can install system deps with:
+
+```sh
+sudo apt-get update && sudo apt-get install git gnuplot
+```
 
-## License
+Generated output (example files written to the output directory):
 
-This project is a fork of [hoxu/gitstats](https://github.com/hoxu/gitstats). Please refer to the original project for licensing details.
+- `index.html`: main HTML report with links to charts and pages.
+- `authors.html`, `lines.html`, `files.html`, `tags.html`, `activity.html`: detail pages for each statistic.
+- `*.dat`, `*.plot`: raw data and gnuplot scripts used to generate images.
+- `*.png`: chart images produced by `gnuplot` (if available).
+- `gitstats_*.pdf`: optional PDF summary produced via `fpdf`.
 
-## Acknowledgements
+Troubleshooting tips:
 
-- Original author: [hoxu/gitstats](https://github.com/hoxu/gitstats)
-- Ported to Python 3 by [lechibang-1512](https://github.com/lechibang-1512)
+- If charts are missing, confirm `gnuplot` is installed and available in your `PATH`.
+- If the script fails with permission errors, ensure you have read access to the git repository and write access to the output directory.
+- Use `--debug` to see the exact git and gnuplot commands being executed; this helps reproduce and fix issues.
+- If you see fpdf deprecation warnings, the PDF is likely still generated. Consider upgrading the `fpdf` package or updating the PDF-generation code to use the current API.