I would like to add JSON output to the git log command.
## Motivation
Machine parsing of git log output is prevalent, but git only provides
human-readable output. Having git output JSON directly solves problems
with the format option or third-party tools. Git has the information
in a machine-readable format. It should output in a machine-readable
format. JSON is ubiquitous and easy to generate, and therefore, it
makes sense to output JSON.
The author of one of the third-party tools says that JSON output is
the natural evolution of the Unix philosophy and should be done
natively for all tools[4].
## Current behaviour
Git log can output human-readable output in several ways. However,
outputting in JSON requires third-party tools or hacking pretty
output.
## Proposed enhancement
Add a –pretty=json flag to output logs in JSON format.
## Alternatives
### Why natively?
The `jc` command parses git log output to convert to JSON[3]. However,
it post processes and has some difficulty with time zones in dates.
Also, the author considers it to be a stopgap until Unix tools can be
adopted to output JSON natively[4], which is what I'm proposing.
In a TIL post[2], Simon Willison showcases a method using pretty
output with nulls piped to jq. This method uses the pretty command to
get delimited output. However, this script doesn't handle all the
output from git log.
Tools like git-log2json[1] parse git output post-hoc, rather than
producing structured output from git.
Providing git log in JSON format will allow us to go to the source,
where we have the log output in machine readable form, and output
directly in machine readable form directly, without going through an
intermediate format
### Why JSON?
JSON is a sufficient and popular output format. It is sufficient in
that it can represent all the fields of git log in a way that allows
for special characters like quotes, newlines, and control characters.
It is also popular. Every language has libraries to parse JSON,
including the command-line utility jq, which can read and mutate JSON.
## Use cases
The JSON can be used by tools or piped into jq to extract and
manipulate the data. Scripts can be written to work with the JSON
output.
## Design outline
* Add a `PRETTY_JSON` constant.
* Create a pretty-json.c file to output JSON log information
* Modify pretty.c to call pretty-json to output JSON when the flag is set.
* Use existing utility functions written in the existing source to
output the JSON.
## Example output
Here’s a sample with two commits:
```JSON
{
"commits": [
{
"commit": "3857aae53f3633b7de63ad640737c657387ae0c6",
"refs": [
"HEAD",
"refs/remotes/origin/main",
"refs/remotes/origin/HEAD"
],
"author": {
"name": "Somebody J. Example",
"email": "somebody@xxxxxxxxxxx",
"date": "2024-09-25T18:23:49-07:00",
"timestamp": "1727313829"
},
"committer": {
"name": "Somebody Else",
"email": "somebody.else@xxxxxxxxxxx",
"date": "2024-09-25T18:24:52-07:00",
"timestamp": "1727313892"
},
"message": "Do a thing\n"
},
{
"commit": "1522467d13a8fe29eb32209f175722df41e224b6",
"merge": [
"f92c61aef0190641e01294dad3b891b28113e1d5",
"7ffcbafbf32185da7dccb4b3f49b871f24ab58c4"
],
"author": {
"name": "Somebody J. Example",
"email": "somebody@xxxxxxxxxxx",
"date": "2024-09-25T18:24:52-07:00",
"timestamp": "1727313892"
},
"committer": {
"name": "Somebody Else",
"email": "somebody.else@xxxxxxxxxxx",
"date": "2024-09-25T18:24:52-07:00",
"timestamp": "1727313892"
},
"message": "Merge something\n\n* This,\n* That, and\n* The other\n"
}
]
}
```
## References
> [1] Context-Driven Testing Toolkit, git-log2json: Convert git log to JSON, GitHub repository, https://github.com/context-driven-testing-toolkit/git-log2json
> [2] Simon Willison, “Convert git log output to JSON using jq,” til.simonwillison.net, March 22 2023. https://til.simonwillison.net/jq/git-log-json
> [3] Kelly Brazil, jc.parsers.git_log: JSON parser for git log, jc documentation, version 1.5. Retrieved via GitHub Pages, https://kellyjonbrazil.github.io/jc/docs/parsers/git_log.html
> [4] Kelly Brazil, Bringing the Unix Philosophy to the 21st Century, Brazil’s Blog, November 26 2019. https://blog.kellybrazil.com/2019/11/26/bringing-the-unix-philosophy-to-the-21st-century/
