mirror of
https://github.com/ejwa/gitinspector.git
synced 2024-09-07 17:01:29 +02:00
314 lines
9.7 KiB
Groff
314 lines
9.7 KiB
Groff
'\" t
|
|
.\" Title: gitinspector
|
|
.\" Author: [see the "AUTHOR" section]
|
|
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
|
|
.\" Date: 12/14/2015
|
|
.\" Manual: The gitinspector Manual
|
|
.\" Source: gitinspector 0.4.2
|
|
.\" Language: English
|
|
.\"
|
|
.TH "GITINSPECTOR" "1" "12/14/2015" "gitinspector 0\&.4\&.2" "The gitinspector Manual"
|
|
.\" -----------------------------------------------------------------
|
|
.\" * Define some portability stuff
|
|
.\" -----------------------------------------------------------------
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.\" http://bugs.debian.org/507673
|
|
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\" -----------------------------------------------------------------
|
|
.\" * set default formatting
|
|
.\" -----------------------------------------------------------------
|
|
.\" disable hyphenation
|
|
.nh
|
|
.\" disable justification (adjust text to left margin only)
|
|
.ad l
|
|
.\" -----------------------------------------------------------------
|
|
.\" * MAIN CONTENT STARTS HERE *
|
|
.\" -----------------------------------------------------------------
|
|
.SH "NAME"
|
|
gitinspector \- statistical analysis tool for git repositories
|
|
.SH "SYNOPSIS"
|
|
.sp
|
|
\fBgitinspector\fR [OPTION]\&... [REPOSITORY]
|
|
.SH "DESCRIPTION"
|
|
.sp
|
|
Analyze and gather statistics about a git repository\&. The defaut analysis shows general statistics per author, which can be complemented with a timeline analysis that shows the workload and activity of each author\&. Under normal operation, gitinspector filters the results to only show statistics about a number of given extensions and by default only includes source files in the statistical analysis\&.
|
|
.sp
|
|
Several output formats are supported, including plain text, HTML, JSON and XML\&.
|
|
.SH "OPTIONS"
|
|
.sp
|
|
List information about the repository in REPOSITORY\&. If no repository is specified, the current directory is used\&. If multiple repositories are given, information will be fetched from the last repository specified\&.
|
|
.sp
|
|
Mandatory arguments to long options are mandatory for short options too\&. Boolean arguments can only be given to long options\&.
|
|
.PP
|
|
\fB\-f, \-\-file\-types\fR=EXTENSIONS
|
|
.RS 4
|
|
A comma separated list of file extensions to include when computing statistics\&. The default extensions used are: java,c,cc,cpp,h,hh,hpp,py,glsl,rb,js,sql\&. Specifying a single
|
|
\fI*\fR
|
|
asterisk character includes files with no extension\&. Specifying two consecutive
|
|
\fI**\fR
|
|
asterisk characters includes all files regardless of extension\&.
|
|
.RE
|
|
.PP
|
|
\fB\-F, \-\-format\fR=FORMAT
|
|
.RS 4
|
|
Defines in which format output should be generated; the default format is
|
|
\fItext\fR
|
|
and the available formats are: html,htmlembedded,json,text,xml (see
|
|
\fBOUTPUT FORMATS\fR)
|
|
.RE
|
|
.PP
|
|
\fB\-\-grading\fR[=BOOL]
|
|
.RS 4
|
|
Show statistics and information in a way that is formatted for grading of student projects; this is the same as supplying the options
|
|
\fB\-HlmrTw\fR
|
|
.RE
|
|
.PP
|
|
\fB\-H, \-\-hard\fR[=BOOL]
|
|
.RS 4
|
|
Track rows and look for duplicates harder; this can be quite slow with big repositories
|
|
.RE
|
|
.PP
|
|
\fB\-l, \-\-list\-file\-types\fR[=BOOL]
|
|
.RS 4
|
|
List all the file extensions available in the current branch of the repository
|
|
.RE
|
|
.PP
|
|
\fB\-L, \-\-localize\-output\fR[=BOOL]
|
|
.RS 4
|
|
Localize the generated output to the selected system language if a translation is available
|
|
.RE
|
|
.PP
|
|
\fB\-m, \-\-metrics\fR[=BOOL]
|
|
.RS 4
|
|
Include checks for certain metrics during the analysis of commits
|
|
.RE
|
|
.PP
|
|
\fB\-r \-\-responsibilities\fR[=BOOL]
|
|
.RS 4
|
|
Show which files the different authors seem most responsible for
|
|
.RE
|
|
.PP
|
|
\fB\-\-since\fR=DATE
|
|
.RS 4
|
|
Only show statistics for commits more recent than a specific date
|
|
.RE
|
|
.PP
|
|
\fB\-T, \-\-timeline\fR[=BOOL]
|
|
.RS 4
|
|
Show commit timeline, including author names
|
|
.RE
|
|
.PP
|
|
\fB\-\-until\fR=DATE
|
|
.RS 4
|
|
Only show statistics for commits older than a specific date
|
|
.RE
|
|
.PP
|
|
\fB\-w, \-\-weeks\fR[=BOOL]
|
|
.RS 4
|
|
Show all statistical information in weeks instead of in months
|
|
.RE
|
|
.PP
|
|
\fB\-x, \-\-exclude\fR=PATTERN
|
|
.RS 4
|
|
An exclusion pattern describing the file paths, revisions, author names or author emails that should be excluded from the statistics; can be specified multiple times (see
|
|
\fBFILTERING\fR)
|
|
.RE
|
|
.PP
|
|
\fB\-h, \-\-help\fR
|
|
.RS 4
|
|
Display help and exit
|
|
.RE
|
|
.PP
|
|
\fB\-\-version\fR
|
|
.RS 4
|
|
Output version information and exit
|
|
.RE
|
|
.SH "OUTPUT FORMATS"
|
|
.sp
|
|
There is support for multiple output formats in gitinspector\&. They can be selected using the \fB\-F\fR/\fB\-\-format\fR flags when running the main gitinspector script\&.
|
|
.PP
|
|
\fBtext (plain text)\fR
|
|
.RS 4
|
|
Plain text with some very simple ANSI formatting, suitable for console output\&. This is the format chosen by default in gitinspector\&.
|
|
.RE
|
|
.PP
|
|
\fBhtml\fR
|
|
.RS 4
|
|
HTML with external links\&. The generated HTML page links to some external resources; such as the JavaScript library JQuery\&. It requires an active internet connection to properly function\&. This output format will most likely also link to additional external resources in the future\&.
|
|
.RE
|
|
.PP
|
|
\fBhtmlembedded\fR
|
|
.RS 4
|
|
HTML with no external links\&. Similar to the HTML output format, but requires no active internet connection\&. As a consequence; the generated pages are bigger (as certain scripts have to be embedded into the generated output)\&.
|
|
.RE
|
|
.PP
|
|
\fBjson\fR
|
|
.RS 4
|
|
JSON suitable for machine consumption\&. If you want to parse the output generated by gitinspector in a script or application of your own; this format is suitable\&.
|
|
.RE
|
|
.PP
|
|
\fBxml\fR
|
|
.RS 4
|
|
XML suitable for machine consumption\&. If you want to parse the output generated by gitinspector in a script or application of your own; this format is suitable\&.
|
|
.RE
|
|
.SH "FILTERING"
|
|
.sp
|
|
gitinspector offers several different ways of filtering out unwanted information from the generated statistics:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBgitinspector \-x myfile\fR, filter out and exclude statistics from all files (or paths) with the string "myfile"
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBgitinspector \-x file:myfile\fR, filter out and exclude statistics from all files (or paths) with the string "myfile"
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBgitinspector \-x author:John\fR, filter out and exclude statistics from all authors containing the string "John"
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBgitinspector \-x email:@gmail\&.com\fR, filter out and exclude statistics from all authors with a gmail account
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBgitinspector \-x revision:8755fb33\fR, filter out and exclude statistics from all revisions containing the hash "8755fb33"
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBgitinspector \-x message:BUGFIX\fR, filter out and exclude statistics from all revisions containing "BUGFIX" in the commit message\&.
|
|
.RE
|
|
.sp
|
|
The gitinspector command also lets you add multiple filtering rules by simply specifying the \-x options several times or by separating each filtering rule with a comma;
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBgitinspector \-x author:John \-x email:@gmail\&.com\fR
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBgitinspector \-x author:John,email:@gmail\&.com\fR
|
|
.RE
|
|
.sp
|
|
Sometimes, sub\-string matching (as described above) is simply not enough\&. Therefore, gitinspector let\(cqs you specify regular expressions as filtering rules\&. This makes filtering much more flexible:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBgitinspector \-x "author:\e^(?!(John Smith))"\fR, only show statistics from author "John Smith"
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBgitinspector \-x "author:\e^(?!([A\-C]))"\fR, only show statistics from authors starting with the letters A/B/C
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fBgitinspector \-x "email:\&.com$"\fR, filter out statistics from all email addresses ending with "\&.com"
|
|
.RE
|
|
.SH "USING GIT TO CONFIGURE GITINSPECTOR"
|
|
.sp
|
|
Options in gitinspector can be set using \fBgit config\fR\&. Consequently, it is possible to configure gitinspector behavior globally (in all git repositories) or locally (in a specific git repository)\&. It also means that settings will be permanently stored\&. All the long options that can be given to gitinspector can also be configured via git config (and take the same arguments)\&.
|
|
.sp
|
|
To configure how gitinspector should behave in all git repositories, execute the following git command:
|
|
.sp
|
|
\fBgit config \-\-global inspector\&.option setting\fR
|
|
.sp
|
|
To configure how gitinspector should behave in a specific git repository, execute the following git command (with the current directory standing inside the repository in question):
|
|
.sp
|
|
\fBgit config inspector\&.option setting\fR
|
|
.SH "AUTHOR"
|
|
.sp
|
|
Originally written by Adam Waldenberg\&.
|
|
.SH "REPORTING BUGS"
|
|
.sp
|
|
Report gitinspector bugs to gitinspector@ejwa\&.se
|
|
.sp
|
|
The gitinspector project page: https://github\&.com/ejwa/gitinspector
|
|
.sp
|
|
If you encounter problems, be sure to read the FAQ first: https://github\&.com/ejwa/gitinspector/wiki/FAQ
|
|
.sp
|
|
There is also an issue tracker at: https://github\&.com/ejwa/gitinspector/issues
|
|
.SH "COPYRIGHT"
|
|
.sp
|
|
Copyright \(co 2012\-2015 Ejwa Software\&. All rights reserved\&. License GPLv3+: GNU GPL version 3 or later http://gnu\&.org/licenses/gpl\&.html\&. This is free software: you are free to change and redistribute it\&. There is NO WARRANTY, to the extent permitted by law\&.
|
|
.SH "SEE ALSO"
|
|
.sp
|
|
\fBgit\fR(1)
|