Gwitlog
Make developers eager to read your commit log by styling it like a social media timeline., (*1)
Based on this commitstrip comic, this tool allows you to take a commit log from a git repo and style it to look like a social media timeline., (*2)
Installation
The package can be installed by adding the "conroyp/gwitlog": "dev-master" package to your project's composer.json., (*3)
[
"require": {
"square1/gwitlog": "0.1.*"
}
]
Usage
Generating the log file
The required format of the git log is generated by running the below command on your repository:, (*4)
git log --pretty=format:'%H -%d %s (%ad) <%an:%ae>', (*5)
Outputting the timeline to screen
<?php
/**
* A simple script to read a git log from a file and render the timeline to screen
*/
require 'vendor/autoload.php';
use \Square1\Gwitlog\Renderer as Renderer;
$gwitlog = new Renderer();
// Provide repo name
$gwitlog->setRepoName('Gwitlog');
// Provide remote repo base (Optional, but it allows us link commits back to the web GUI)
// Currently support bitbucket and github urls
$gwitlog->setRemoteHost('https://github.com/square1-io/gwitlog');
// Log file generated based on git log command:
// git log --pretty=format:'%H -%d %s (%ad) <%an:%ae>' > git.log
$gwitlog->setInputFile('git.log');
// Generate output and render to screen
$gwitlog->render();
Outputting the timeline to file
<?php
/**
* A simple script to read a git log from a file and render the timeline to a file
*/
require 'vendor/autoload.php';
use \Square1\Gwitlog\Renderer as Renderer;
$gwitlog = new Renderer();
// Provide repo name
$gwitlog->setRepoName('Gwitlog');
// Provide remote repo base (Optional, but it allows us link commits back to the web GUI)
// Currently support bitbucket and github urls
$gwitlog->setRemoteHost('https://github.com/square1-io/gwitlog');
// Log file generated based on git log command:
// git log --pretty=format:'%H -%d %s (%ad) <%an:%ae>' > git.log
$gwitlog->setInputFile('git.log');
// Write to file timeline.html
$gwitlog->outputToFile('timeline.html');
Reading from stdin rather than a flat file
Gwitlog also supports reading from an input stream, allowing the git log command to be piped through the script without writing the intermediary git.log file., (*6)
<?php
/**
* A simple script to read a git log from stdin and render the timeline to screen
*/
require 'vendor/autoload.php';
use \Square1\Gwitlog\Renderer as Renderer;
$gwitlog = new Renderer();
// Provide repo name
$gwitlog->setRepoName('Gwitlog');
// Provide remote repo base (Optional, but it allows us link commits back to the web GUI)
// Currently support bitbucket and github urls
$gwitlog->setRemoteHost('https://github.com/square1-io/gwitlog');
// Read from input stream
$input = fopen('php://stdin', 'r');
$gwitlog->setInputStream($input);
// Generate output and render to screen
$gwitlog->render();
Saving the above as gwitlog.php allows us to run:, (*7)
git log --pretty=format:'%H -%d %s (%ad) <%an:%ae>' | gwitlog.php > timeline.html, (*8)
That leaves a file (timeline.html) containing the formatted timeline. This allows things like a post-build hook in a local testing environment to generate a new timeline for the team to review after each successful merge., (*9)
Customising the output
It's possible to customise the output of the result. We use the Blade templating language, most commonly found in Laravel projects., (*10)
The Renderer can be given the location of a directory containing customised views. It will expect to find three views here - header.blade.php, gwit.blade.php and footer.blade.php. The call to pass on this directory can be made at any time before the outputToFile or render functions are called., (*11)
<?php
/**
* A simple script to read a git log from stdin and render the timeline to screen, using
* customised views
*/
require 'vendor/autoload.php';
use \Square1\Gwitlog\Renderer as Renderer;
$gwitlog = new Renderer();
// Provide repo name
$gwitlog->setRepoName('Gwitlog');
// Provide remote repo base (Optional, but it allows us link commits back to the web GUI)
// Currently support bitbucket and github urls
$gwitlog->setRemoteHost('https://github.com/square1-io/gwitlog');
// Use our custom templates
$gwitlog->setViewDirectory(__DIR__ . '/../views/gwitlog');
// Read from input stream
$input = fopen('php://stdin', 'r');
$gwitlog->setInputStream($input);
// Generate output and render to screen
$gwitlog->render();
By default, these views shall be cached to /tmp. If you have permission issues with your deployment or just wish for all of your project views to be cached in one place, call setCacheDirectory($path). This will update the cache directory used by the renderer., (*12)
Over-riding default size limits
A maximum of 20,000 commits will be handled by default. If you want to try processing more than this, calling setMaxEntries($limit) will increase the processing limit., (*13)
Tests
phpunit, (*14)
Roadmap
- Parsing regular log output, allowing multi-line commits to be visible over multiple lines
- Handling the output of
--graph to better attach branch names to all commits on that branch
- Accept url of public project and download git log from there automatically
Wallogit.com
