From 90be8407ccc34a0ee26ee25b1ff1384c393138c0 Mon Sep 17 00:00:00 2001 From: Aki Date: Sun, 11 Feb 2024 00:31:45 +0100 Subject: Added a manpage --- Makefile | 6 +++++- activity.1 | 44 ++++++++++++++++++++++++++++++++++++++++++++ activity.lua | 42 ++++++++++++++++++++++++++++++++++++++++++ generate.lua | 42 ------------------------------------------ 4 files changed, 91 insertions(+), 43 deletions(-) create mode 100644 activity.1 create mode 100755 activity.lua delete mode 100755 generate.lua diff --git a/Makefile b/Makefile index 236b04d..161fed2 100644 --- a/Makefile +++ b/Makefile @@ -2,6 +2,8 @@ LUA_VERSION=5.4 PREFIX=/usr/local BINDIR=$(PREFIX)/bin DATADIR=$(PREFIX)/share +MANDIR=$(DATADIR)/man +MAN1DIR=$(MANDIR)/man1 LUA_LMOD=$(DATADIR)/lua/$(LUA_VERSION) all: @@ -10,11 +12,13 @@ all: install: install -m644 -Dt $(DESTDIR)$(LUA_LMOD)/activity activity/*.lua install -m644 -Dt $(DESTDIR)$(LUA_LMOD)/activity/formats activity/formats/*.lua - install -m755 -DT generate.lua $(DESTDIR)$(BINDIR)/activity + install -m755 -DT activity.lua $(DESTDIR)$(BINDIR)/activity + install -m644 -Dt $(DESTDIR)$(MAN1DIR) activity.1 uninstall: rm -rf $(DESTDIR)$(LUA_LMOD)/activity rm -f $(DESTIR)$(BINDIR)/activity + rm -f $(DESTIR)$(MAN1DIR)/activity.1 test: busted diff --git a/activity.1 b/activity.1 new file mode 100644 index 0000000..0ed1eb3 --- /dev/null +++ b/activity.1 @@ -0,0 +1,44 @@ +.TH activity 1 "2024-02-11" +.SH NAME +activity - generates a rolling or yearly activity chart for git repositories +.SH SYNOPSIS +.B activity +.RB [ \-y +.IR year ] +.RB [ \-f +.IR format ] +.RB [ \-A | \-C +.IR email ]... +.RI [ repositories ]... +.SH DESCRIPTION +Activity counts daily commits in selected repositories and creates a calendar year chart or up to last 53 weeks rolling +chart. Chart is a day-based heatmap, where the colour intensifies along the number of commits. +.P +Optionally, a filter can be applied to only count commits committed or authored by a person using selected e-mails. More +than one address can be provided and if any of them match, the commit will be included. +.SH EXIT STATUS +If no errors were encountered during chart generation, a +.B 0 +exit status is returned from the process. If an error occurred, a non-zero exit status is returned. Not all errors are +considered critical and in some cases an incomplete chart may be still generated. +.SH EXAMPLES +.SS Print rolling chart for the repository owning current working directory +.RS +.EX +$ activity +.EE +.RE +.SS Generate SVG chart for 2023 for all repositories in a list +.RS +.EX +$ xargs activity -y2023 -fsvg activity.svh +.EE +.RE +.SS Generate HTML5 rolling chart filtered by matching either author or committer in all repositories in a list +.RS +.EX +$ xargs activity -Aplease@ignore.pl -Cplease@ignore.pl -fhtml5 activity.html +.EE +.RE +.SH SEE ALSO +.BR git (1) diff --git a/activity.lua b/activity.lua new file mode 100755 index 0000000..a97e79d --- /dev/null +++ b/activity.lua @@ -0,0 +1,42 @@ +#!/usr/bin/lua +local args = require "pl.lapp" [[ +Generates activity chart + -f (string default 'ansi') Output format of the chart + -y (optional number) Generate yearly chart for selected year + -A... (optional string) Author e-mail addresses to include in chart + -C... (optional string) Committer e-mail addresses to include in chart + (optional string) Paths to repositories with activity + +By default, tool will generate a rolling chart for selected repositories. If no +repositories were selected, current working directory will be tried. +]] +local generators = require "activity.generators" +local git = require "activity.git" +local ok, maybe_format = pcall(require, "activity.formats." .. args.f) +if not ok then + io.stderr:write(("could not find specified format: %q\n\n"):format(args.f)) + io.stderr:write(maybe_format, "\n") + os.exit(1) +end +local maybe_year = args.y or "rolling" +if #args.repos < 1 then + table.insert(args.repos, ".") +end +local filter, by_author, by_committer +if #args.A > 0 then + by_author = git.any_value_filter("author", args.A) +end +if #args.C > 0 then + by_committer = git.any_value_filter("committer", args.C) +end +if by_committer and by_author then + function filter (entry) + return by_author(entry) or by_committer(entry) + end +end +filter = filter or by_author or by_committer +local errors, lookup = git.lookup(args.repos, filter) +io.write(generators.generate_table(maybe_year, lookup, maybe_format)) +if errors then + os.exit(1) +end diff --git a/generate.lua b/generate.lua deleted file mode 100755 index a97e79d..0000000 --- a/generate.lua +++ /dev/null @@ -1,42 +0,0 @@ -#!/usr/bin/lua -local args = require "pl.lapp" [[ -Generates activity chart - -f (string default 'ansi') Output format of the chart - -y (optional number) Generate yearly chart for selected year - -A... (optional string) Author e-mail addresses to include in chart - -C... (optional string) Committer e-mail addresses to include in chart - (optional string) Paths to repositories with activity - -By default, tool will generate a rolling chart for selected repositories. If no -repositories were selected, current working directory will be tried. -]] -local generators = require "activity.generators" -local git = require "activity.git" -local ok, maybe_format = pcall(require, "activity.formats." .. args.f) -if not ok then - io.stderr:write(("could not find specified format: %q\n\n"):format(args.f)) - io.stderr:write(maybe_format, "\n") - os.exit(1) -end -local maybe_year = args.y or "rolling" -if #args.repos < 1 then - table.insert(args.repos, ".") -end -local filter, by_author, by_committer -if #args.A > 0 then - by_author = git.any_value_filter("author", args.A) -end -if #args.C > 0 then - by_committer = git.any_value_filter("committer", args.C) -end -if by_committer and by_author then - function filter (entry) - return by_author(entry) or by_committer(entry) - end -end -filter = filter or by_author or by_committer -local errors, lookup = git.lookup(args.repos, filter) -io.write(generators.generate_table(maybe_year, lookup, maybe_format)) -if errors then - os.exit(1) -end -- cgit v1.1