Skip to content

Conversation

@kunal-g
Copy link

@kunal-g kunal-g commented Jun 26, 2025

  • jq is a quite popular cli tool for processing json docs.
  • This commit adds support for generating the hunk headers that could be
    copied into a jq command (minus the first .).
    • For that, we add:
      • a render option - JQPATH - so that it can be explicitly controlled.
      • a JqPath() method on the Path - to render the path.
      • a call to JqPath() in diff_write.go:Render() - based on the
        passed render options.
      • also, corresponding tests in diff_write_test.go

This change allows us to simply copy the dotted JSON path from the hunk header and inspect that element with jq.

  • For example: I can run
    • jq '.<copied-json-path-from-hunk-header>' <original_file>.json
    • jq '.<copied-json-path-from-hunk-header>' <updated_file>.json
    • Please note that the starting . needs to be explicitly added in the above jq commands.

Signed-off-by: Kunal Gangakhedkar [email protected]

kunal-g added 2 commits June 26, 2025 12:50
* `jq` is a pretty popular cli tool for processing json docs.
* This commit adds support for generating the hunk headers that could be
  copied into a jq command (minus the first '.').
  * For that, we add:
    * a render option - `JQPATH` - so that it can be explicitly
      controlled.
    * a `JqPath()` method on the `Path` - to render the path.
    * a call to `JqPath()` in `diff_write.go:Render()` - based on the
      passed render options.
    * also, corresponding tests in `diff_write_test.go`

Signed-off-by: Kunal Gangakhedkar <[email protected]>
Passing this flag to the 'jd' binary should render the hunk header as jq
compatible json path.

Signed-off-by: Kunal Gangakhedkar <[email protected]>
@kunal-g kunal-g changed the title Add support for [jq](https://jqlang.org/) compatible hunk headers. Add support for jq compatible hunk headers. Jun 26, 2025
@josephburnett
Copy link
Owner

@kunal-g can you tell me more about what you're trying to accomplish with this change. It's nice that the headers could be jq compatible. What is a workflow that you would like to enable? E.g. are you diffing two JSON files, and then want to look at what is contained in a third? If I can understand more about the goal then maybe we can extend this more comprehensively. Maybe there is a different format entirely that would make a workflow including jd more smooth.

@kunal-g
Copy link
Author

kunal-g commented Jul 1, 2025

@josephburnett :

the typical use-case here is:

  • I have 2 large-ish JSON files (~50kb each) with minor changes (say, 1-2 fields changed/added/deleted) deeper in the hierarchy.
  • When looking only at the diff generated by jd, I don't get complete picture of the change wrt the structure.
  • While the compactness of the diff is immensely valuable for storage, it's important for us to make sense of that change in the structure view.
  • Sometimes, just the diff may be sufficient; but other times, I may need to pull the full JSON objects and navigate the hierarchy to get the context of the change.

With jq compatible hunk headers, navigating that hierarchy to reach correct context easily becomes possible in 1 single command - I can simply remove the last element (or few elements, if required) from the json path and get to the context.


Comparison with unified diff

It's difficult to pre-determine how much of context we need to capture in the diff especially when dealing with arrays.

Unified diff is line-oriented and hence, specifying no. of lines with the -U option works to capture enough no. of lines as context.

JSON data can be in minified form - not suitable for line-oriented context.


I hope this gives you enough context about the motivation for the change.

I am more than happy to collaborate if you have any alternative suggestions that can help with the use-case 😃

@kunal-g
Copy link
Author

kunal-g commented Jul 17, 2025

@josephburnett bumping up.
Any feedback on this PR?
If you think this looks good, can you please merge this PR?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants