From 757f070c3e2507a3a1a9a40f93274596e9c4b820 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Sun, 6 Oct 2024 23:53:16 +0100 Subject: [PATCH] update docs - fixes #93 - follow-up to #92 --- .meta/.git-fame.1.md | 4 +- README.rst | 1 + gitfame/_gitfame.py | 3 +- gitfame/git-fame.1 | 138 ++++++++++++++++++------------------------- 4 files changed, 62 insertions(+), 84 deletions(-) diff --git a/.meta/.git-fame.1.md b/.meta/.git-fame.1.md index f11ca79..32f2419 100644 --- a/.meta/.git-fame.1.md +++ b/.meta/.git-fame.1.md @@ -1,5 +1,5 @@ % GIT-FAME(1) git-fame User Manuals -% Casper da Costa-Luis +% Casper da Costa-Luis (https://github.com/casperdcl) % 2016-2023 # NAME @@ -12,7 +12,7 @@ git-fame [\--help | *options*] [<*gitdir*>...] # DESCRIPTION -See . +See https://github.com/casperdcl/git-fame. Probably not necessary on UNIX systems: diff --git a/README.rst b/README.rst index b2d067e..7b1ac24 100644 --- a/README.rst +++ b/README.rst @@ -196,6 +196,7 @@ Documentation --incl= Included files [default: .*]. See `--excl` for format. --since= Date from which to check. Can be absoulte (eg: 1970-01-31) or relative to now (eg: 3.weeks). + --until= Date to which to check. See `--since` for format. --cost= Include time cost in person-months (COCOMO) or person-hours (based on commit times). Methods: month(s)|cocomo|hour(s)|commit(s). diff --git a/gitfame/_gitfame.py b/gitfame/_gitfame.py index 490b4b8..435d185 100755 --- a/gitfame/_gitfame.py +++ b/gitfame/_gitfame.py @@ -21,8 +21,7 @@ --incl= Included files [default: .*]. See `--excl` for format. --since= Date from which to check. Can be absoulte (eg: 1970-01-31) or relative to now (eg: 3.weeks). - --until= Date to which to check. Can be absoulte (eg: 1970-01-31) - or relative to now (eg: 3.weeks). + --until= Date to which to check. See `--since` for format. --cost= Include time cost in person-months (COCOMO) or person-hours (based on commit times). Methods: month(s)|cocomo|hour(s)|commit(s). diff --git a/gitfame/git-fame.1 b/gitfame/git-fame.1 index ec11c94..669cfb5 100644 --- a/gitfame/git-fame.1 +++ b/gitfame/git-fame.1 @@ -1,49 +1,27 @@ -.\" Automatically generated by Pandoc 2.19.2 +.\" Automatically generated by Pandoc 3.3 .\" -.\" Define V font for inline verbatim, using C font in formats -.\" that render this, and otherwise B font. -.ie "\f[CB]x\f[]"x" \{\ -. ftr V B -. ftr VI BI -. ftr VB B -. ftr VBI BI -.\} -.el \{\ -. ftr V CR -. ftr VI CI -. ftr VB CB -. ftr VBI CBI -.\} -.TH "GIT-FAME" "1" "2016-2023" "git-fame User Manuals" "" -.hy +.TH "GIT\-FAME" "1" "2016\-2023" "git\-fame User Manuals" .SH NAME -.PP -git-fame - Pretty-print \f[V]git\f[R] repository collaborators sorted by -contributions. +git\-fame \- Pretty\-print \f[CR]git\f[R] repository collaborators +sorted by contributions. .SH SYNOPSIS -.PP -git-fame [--help | \f[I]options\f[R]] [<\f[I]gitdir\f[R]>\&...] +git\-fame [\-\-help | \f[I]options\f[R]] [<\f[I]gitdir\f[R]>\&...] .SH DESCRIPTION -.PP -See . +See https://github.com/casperdcl/git\-fame. .PP Probably not necessary on UNIX systems: .IP -.nf -\f[C] -git config --global alias.fame \[dq]!python -m gitfame\[dq] -\f[R] -.fi +.EX +git config \-\-global alias.fame \[dq]!python \-m gitfame\[dq] +.EE .PP For example, to print statistics regarding all source files in a -C++/CUDA repository (\f[V]*.c/h/t(pp), *.cu(h)\f[R]), carefully handling -whitespace and line copies: +C++/CUDA repository (\f[CR]*.c/h/t(pp), *.cu(h)\f[R]), carefully +handling whitespace and line copies: .IP -.nf -\f[C] -git fame --incl \[aq]\[rs].[cht][puh]{0,2}$\[aq] -twMC -\f[R] -.fi +.EX +git fame \-\-incl \[aq]\[rs].[cht][puh]{0,2}$\[aq] \-twMC +.EE .SH OPTIONS .TP @@ -51,96 +29,96 @@ Git directory [default: ./]. May be specified multiple times to aggregate across multiple repositories. .TP --h, --help +\-h, \-\-help Print this help and exit. .TP --v, --version +\-v, \-\-version Print module version and exit. .TP ---branch=\f[I]b\f[R] +\-\-branch=\f[I]b\f[R] Branch or tag [default: HEAD] up to which to check. .TP ---sort=\f[I]key\f[R] +\-\-sort=\f[I]key\f[R] [default: loc]|commits|files|hours|months. .TP ---loc=\f[I]type\f[R] -surv(iving)|ins(ertions)|del(etions) What \f[V]loc\f[R] represents. +\-\-loc=\f[I]type\f[R] +surv(iving)|ins(ertions)|del(etions) What \f[CR]loc\f[R] represents. Use `ins,del' to count both. -defaults to `surviving' unless \f[V]--cost\f[R] is specified. +defaults to `surviving' unless \f[CR]\-\-cost\f[R] is specified. .TP ---excl=\f[I]f\f[R] +\-\-excl=\f[I]f\f[R] Excluded files (default: None). -In no-regex mode, may be a comma-separated list. +In no\-regex mode, may be a comma\-separated list. Escape (\[rs],) for a literal comma (may require \[rs]\[rs], in shell). .TP ---incl=\f[I]f\f[R] +\-\-incl=\f[I]f\f[R] Included files [default: .*]. -See \f[V]--excl\f[R] for format. +See \f[CR]\-\-excl\f[R] for format. .TP ---since=\f[I]date\f[R] +\-\-since=\f[I]date\f[R] Date from which to check. -Can be absoulte (eg: 1970-01-31) or relative to now (eg: 3.weeks). +Can be absoulte (eg: 1970\-01\-31) or relative to now (eg: 3.weeks). .TP ---until=\f[I]date\f[R] +\-\-until=\f[I]date\f[R] Date to which to check. -Can be absoulte (eg: 1970-01-31) or relative to now (eg: 3.weeks). +See \f[CR]\-\-since\f[R] for format. .TP ---cost=\f[I]method\f[R] -Include time cost in person-months (COCOMO) or person-hours (based on +\-\-cost=\f[I]method\f[R] +Include time cost in person\-months (COCOMO) or person\-hours (based on commit times). Methods: month(s)|cocomo|hour(s)|commit(s). -May be multiple comma-separated values. -Alters \f[V]--loc\f[R] default to imply `ins' (COCOMO) or `ins,del' +May be multiple comma\-separated values. +Alters \f[CR]\-\-loc\f[R] default to imply `ins' (COCOMO) or `ins,del' (hours). .TP --R, --recurse +\-R, \-\-recurse Recursively find repositories & submodules within . .TP --n, --no-regex -Assume are comma-separated exact matches rather than regular expressions -[default: False]. +\-n, \-\-no\-regex +Assume are comma\-separated exact matches rather than regular +expressions [default: False]. NB: if regex is enabled `,' is equivalent to `|'. .TP --s, --silent-progress -Suppress \f[V]tqdm\f[R] [default: False]. +\-s, \-\-silent\-progress +Suppress \f[CR]tqdm\f[R] [default: False]. .TP ---warn-binary +\-\-warn\-binary Don\[cq]t silently skip files which appear to be binary data [default: False]. .TP --e, --show-email +\-e, \-\-show\-email Show author email instead of name [default: False]. .TP ---enum +\-\-enum Show row numbers [default: False]. .TP --t, --bytype +\-t, \-\-bytype Show stats per file extension [default: False]. .TP --w, --ignore-whitespace +\-w, \-\-ignore\-whitespace Ignore whitespace when comparing the parent\[cq]s version and the child\[cq]s to find where the lines came from [default: False]. --M Detect intra-file line moves and copies [default: False]. --C Detect inter-file line moves and copies [default: False]. +\-M Detect intra\-file line moves and copies [default: False]. +\-C Detect inter\-file line moves and copies [default: False]. .TP ---ignore-rev=\f[I]rev\f[R] +\-\-ignore\-rev=\f[I]rev\f[R] Ignore changes made by the given revision (requires -\f[V]--loc=surviving\f[R]). +\f[CR]\-\-loc=surviving\f[R]). .TP ---ignore-revs-file=\f[I]f\f[R] +\-\-ignore\-revs\-file=\f[I]f\f[R] Ignore revisions listed in the given file (requires -\f[V]--loc=surviving\f[R]). +\f[CR]\-\-loc=surviving\f[R]). .TP ---format=\f[I]format\f[R] +\-\-format=\f[I]format\f[R] Table format [default: pipe]|md|markdown|yaml|yml|json|csv|tsv|tabulate. -May require \f[V]git-fame[]\f[R], -e.g.\ \f[V]pip install git-fame[yaml]\f[R]. -Any \f[V]tabulate.tabulate_formats\f[R] is also accepted. +May require \f[CR]git\-fame[]\f[R], +e.g.\ \f[CR]pip install git\-fame[yaml]\f[R]. +Any \f[CR]tabulate.tabulate_formats\f[R] is also accepted. .TP ---manpath=\f[I]path\f[R] -Directory in which to install git-fame man pages. +\-\-manpath=\f[I]path\f[R] +Directory in which to install git\-fame man pages. .TP ---log=\f[I]lvl\f[R] +\-\-log=\f[I]lvl\f[R] FATAL|CRITICAL|ERROR|WARN(ING)|[default: INFO]|DEBUG|NOTSET. .SH AUTHORS -Casper da Costa-Luis . +Casper da Costa\-Luis (https://github.com/casperdcl).