Prerequisites & Dependencies
You need Swift 4.2+ and Swift Tools 4.2+.
You will also need a GitHub personal access token. Generate one at https://github.com/settings/tokens. This can be specified as an argument when executing
github-analysis, but it is most convenient to set the
GITHUB_ANALYSIS_TOKEN environment variable.
Download Xcode, then install command line tools.
Download or build Swift 4.2 and the Foundation library.
These dependencies will be downloaded and linked against automatically by the Swift Package Manager.
- SwiftCheck (only used by test targets)
swift package update
--help option prints out help at the command line.
The script will create a cache file if it can in the current working directory. This cache file is not required, but if you maintain the cache file over time, the script will have more GitHub history to analyze than it is allowed to grab with the GitHub events API.
The simplest usage is to run the script against one owner (i.e. a GitHub user or organization) and one or more repositories. This will run analysis on as many events as possible as far back in time as the GitHub events API will go (note it is limited to 90 days or 300 events per repository, whichever comes first).
Note that the owner slug must match the one in the webaddress for your repositories (do not use an email address).
github-analysis owner repo1,repo2
This will print stats out to the terminal.
You can generate a CSV file in addition to outputting stats to the terminal. The CSV file contains slightly more information and it can be a much more convenient format for looking at or manipulating the data.
github-analysis owner repo1,repo2,repo3 --csv
Set Date Limit
You can choose to only analyze events occuring after a certain date (and/or before a certain date with
github-analysis owner repo --later-than=2018-09-15
You can specify a list of users to analyze and all other users that have contributed to the given repositories will be ignored.
github-analysis owner repo --users=user1,user2,user3
Hide warning and caveat footnotes
By default, values will get annotated if there is a warning or a caveat to be aware of for the value. You can disable these footnotes to get cleaner output (perhaps to import into a spreadsheet and analyze further).
github-analysis owner repo --skip-footnotes
Please fork the repository and make any additions that suit your needs. I welcome Pull Requests back into this repository; I'm never too busy to maintain a pet project but I might get too busy to make valuable additions myself.
- Do not add any Xcode project or environment files to the repository. The Xcode project should remain entirely buildable using Swift Package Manager (see Dev Env section below).
- After adding new tests, run
swift test --generate-linuxmainand commit the changes that script makes to the repository. This keeps unit testing on Linux in sync with unit testing on OS X.
Just a note for anyone unfamiliar with the Swift Package Manager:
You can still do your development in Xcode, and I prefer to do so. Make sure that any Groups you create correlate to folders in the repository and the rest should be cake.
swift package generate-xcodeproj to get a project set up on your machine.
Help us keep the lights on
0.4.0 - Nov 3, 2018
I think I've finally got the averages sorted out. Averages for the Pull Request open lengths were throwing me for several loops but now they seem accurate and current behavior is tested.
- Breaking changes to pull request stats (but also fixed bugs).
- Lots of new testing.
- several new arguments (see
- Repository averages get exposed alongside user averages in the stats table.
0.3.0 - Oct 28, 2018
- More restructuring.
--helpfor information on several new parameters.
- Removed Alamofire (allows support of Linux).
- Support for Linux (tested on Ubuntu 16.0.4).
0.2 - Oct 15, 2018
I restructured the various
Stat structures to make the naming cleaner (breaking change).
I added a few test cases for things I was most concerned about, but far far from complete coverage.
There are a few new features.
--help is the easiest way to catch up.
0.1.0 - Oct 8, 2018
With the most recent addition of the
--earlier-than flag to go along with
--users, the functionality of the script seems useful enough to call v0.1.0.
More than adding features, the thing that will get v1.0 released is additional time in-use by me and test coverage (currently sorely lacking and causing me a lot of uncertainty about whether the script is behaving correctly all the time or not).