Prerequisites & Dependencies
You need Swift 4.2+ and Swift Tools 4.2+.
Download Xcode, then install command line tools.
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.
At the moment you can only build GitHubAnalysis for platforms that Alamofire will build for, but in the future I will be removing that dependency so that the script can be run on Linux platforms as well.
These dependencies will be downloaded and linked against automatically by the Swift Package Manager.
- SwiftCheck (only used by test targets)
swift package resolve
--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 analyse events occuring after a certain date.
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
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.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).