From b577575f31f97b3f171103c4eec493bc4ddca940 Mon Sep 17 00:00:00 2001 From: sideshowbarker Date: Fri, 12 Jul 2024 20:02:14 +0900 Subject: [PATCH] Initial commit --- LICENSE | 21 ++++ README.md | 288 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ git-gloss | 212 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 521 insertions(+) create mode 100644 LICENSE create mode 100644 README.md create mode 100755 git-gloss diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..8394c08 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 sideshowbarker + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..4a66433 --- /dev/null +++ b/README.md @@ -0,0 +1,288 @@ +## git-gloss ✨ makes git logs show PR/issue/review links + +`git-gloss` automatically adds [git notes](https://scottchacon.com/2010/08/25/notes/) to all your git logs — with GitHub PR/issue/reviewer/author links. + +--- + +### How to use git-gloss + +You can download and run `git-gloss` within a directory having a GitHub repo clone by just doing this: + +``` +curl -fsSLO https://sideshowbarker.github.io/git-gloss/git-gloss && bash ./git-gloss +``` + +That will add [git notes](https://scottchacon.com/2010/08/25/notes/) locally for all commits in the local commit history with an associated GitHub pull request. + +Then, when you run `git log`, the log output for each commit will look something like this: + +``` +commit 9812031a02e539f08a6936e9c17d919a44c912b8 +Author: Jonatan Klemets +Date: Sun Jul 23 19:38:04 2023 +0300 + + LibWeb: Implement spec-compliant integer parsing + + This patch adds two new methods named `parse_non_negative_integer` and + `parse_integer` inside the `Web::HTML` namespace that uses `StringUtils` + under the hood but adds a bit more logic to make it spec compliant. + +Notes: + Author: https://github.com/Jon4t4n 🔰 + Commit: https://github.com/SerenityOS/serenity/commit/9812031a02 + Pull-request: https://github.com/SerenityOS/serenity/pull/20140 + Issue: https://github.com/SerenityOS/serenity/issues/19937 + Reviewed-by: https://github.com/AtkinsSJ ✅ + Reviewed-by: https://github.com/nico +``` + +🔰 – indicates this is author’s first commit to the repo\ +✅ – indicates a review approval + +--- + +> [!TIP] +> If you want to put notes in the logs for multiple repos, see the [Add a “git gloss” command](#add-a-git-gloss-command) section for a how-to on setting up a new `git gloss` command that you can run just as you would any other `git` command. + +--- + +### How to share the notes + +Once `git-gloss` finishes running, here’s how you can share the notes with everyone in your GitHub project: + +1. Push the notes back to your project remote at GitHub by running this command: + + ``` + git push origin 'refs/notes/*' + ``` + +2. Others in your project can then fetch the notes from GitHub by running this command: + + ``` + git fetch origin 'refs/notes/*:refs/notes/*' + ``` + + Alternatively, rather than running the above command manually, others in the project can update their git configuration by running the following command; + + ``` + git config --add remote.origin.fetch '+refs/notes/*:refs/notes/*' + ``` + + That will cause all notes to be fetched from the remote every time they use `git fetch` or `git pull`. + +3. Run `git-gloss` again to add notes for any new commits made after the last time you ran `git-gloss`. + +4. Keep your project’s notes up to date by repeating steps 1 to 3 at a regular cadence (e.g., once day or so). + +--- + +### How long does it take? + +`git-gloss` can process at most about 1000 commits per hour — about 17 or 18 commits per minute. + +So, the first time you run it in a repo with many commits, it’ll take a long time — hours, or even a day or more. + +For example, if your repo has somewhere around 1000 commits, it’ll take at least 1 hour to finish. If your repo has somewhere around 10,000 commits, it’ll take more than 10 hours. And so on. + +> [!NOTE] +> You can stop `git-gloss` at any time with Ctrl-C. After stopping it, when you run it again, it will start off wherever it left off. So, if you have a repo with somewhere around 2000 commits, and you stopped `git-gloss` after it was running for about an hour, then it will run for about another hour before it finishes. + +### How to “back up” notes + +Given how long (multiple hours) it can take `git-gloss` to add all notes for a large history, you should do this: + +1. Periodically stop `git-gloss` (say, once an hour), using Ctrl-C. + +2. Run the following command to push your (partial) notes to your project repo: + + ``` + git push origin 'refs/notes/*' + ``` + +3. Restart `git-gloss`, to continue adding more notes. + +4. Repeat steps 1 to 3 periodically (say, once an hour) until `git-gloss` finishes. + +> [!IMPORTANT] +> Doing the steps above will ensure that you have a “backup” of the notes you’ve generated so far — and if ever needed, you can then “restore” your notes from that backup by running the following command: +> +> ``` +> git fetch origin 'refs/notes/*:refs/notes/*' +> ``` + +### Why is it so slow? + +For each commit `git-gloss` processes, it makes 4 calls to GitHub API endpoints — requiring network resources and time. And in a typical environment, for each commit the total time needed (mostly due to those calls) happens to work out to 3.5 seconds or so — which means it can process only about 17 or 18 commits per minute. + +Regardless, the GitHub API has [rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api) that prevent making more than 5000 requests per hour — which works out to about 83 requests per minute. And so, because `git-gloss` makes 4 requests for each commit, that also limits it to being able to make only enough requests per minute for 20–21 commits at most (20 ⨉ 4 ⨉ 60 = 4800). + +> [!TIP] +> If you have a connection with very high bandwidth, it’s imaginable that `git-gloss` might end up taking less than 3 seconds for each commit — which means it might exceed that 5000-requests-per-hour rate limit. +> +> If you do exceed the limit, set the [`GH_THROTTLE`](#gh_throttle) environment variable to a high-enough value to prevent that. + +### How to avoid 403s + +You must have the [`GH_TOKEN` or `GITHUB_TOKEN`](https://cli.github.com/manual/gh_help_environment) environment variables set in your environment in order to use `git-gloss` — with the values set to a [GitHub authentication token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). Otherwise, `git-gloss` will fail with 403 errors less than a minute after you start it — after processing only 15 or so commits. + +If you *do* already have the `GH_TOKEN` or `GITHUB_TOKEN` environment variables set, and `git-gloss` is failing with 403 errors — then you’ll need to set [`GH_THROTTLE`](#gh_throttle) to a high-enough value to avoid exceeding GitHub’s [rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api). + +### How to fix errors + +`git-gloss` doesn’t yet have error handling for the case where a call to the GitHub API fails. So you can keep a log of its output, and review it after `git-gloss` finishes. You can create a log by invoking `git-gloss` like this: + +``` +tmpfile=$(mktemp) && echo "Logging output to $tmpfile"; +git-gloss 2>&1 | tee tmpfile +``` + +That creates a log file and sends the output to both the terminal and the log file (using the `mktemp` and `tee` utilities, which are standard in any Linux/Unix environment — including the macOS Terminal/shell environment). + +After `git-log` finishes (or even as it’s running), you can review the log for any unhandled error output. + +> [!NOTE] +> You should [raise an issue](https://github.com/sideshowbarker/git-gloss/issues/new) if you do find any unhandled errors. + +For each unhandled error you find, you’ll need to complete the following steps: + +1. Remove any note which `git-gloss` may have added for the given commit: + + ``` + git notes remove 67c727177e + ``` + +2. (Re)add a note for the given commit, by running `git-gloss` with the commit hash specified: + + ``` + git-gloss 67c727177e + ``` + +> [!CAUTION] +> `git-gloss` provides no way to undo its actions and remove all notes it added. The only practical way to undo its actions may be to completely remove all notes, including any notes you may have added by other means. +> +> But if you haven’t added notes by any other means: To remove all `git-gloss`-added notes, run this: +> +> ``` +> git update-ref -d refs/notes/commits +> ``` + +### How to fix “loose objects” + +``` +Auto packing the repository in background for optimum performance. +See "git help gc" for manual housekeeping. +warning: The last gc run reported the following. Please correct the root cause +and remove .git/gc.log +Automatic cleanup will not be performed until the file is removed. + +warning: There are too many unreachable loose objects; run 'git prune' to remove them. +``` + +### Dependencies + +* `git` – any version ([v2.42+](https://stackoverflow.com/a/76633969/)) with support for the `--no-separator` option for the `git notes` command + +* `jq` – [https://jqlang.github.io/jq/](https://jqlang.github.io/jq/) (JSON processor) + +* `gh` – [https://cli.github.com/](https://cli.github.com/) (GitHub CLI), with the [`GH_TOKEN` or `GITHUB_TOKEN`](https://cli.github.com/manual/gh_help_environment) environment variables set + +* `grep` – any grep-compatible program + +> [!IMPORTANT] +> On macOS in particular, [GNU grep](https://apple.stackexchange.com/a/193300) — rather than than the Apple-provided `grep` — is recommended,for performance reasons; example: +> +> ``` +> brew install grep +> ``` + +### Environment variables + +You can affect the `git-gloss` behavior using the environment variables described in this section. + +> [!TIP] +> Rather than separately exporting each environment variable to your shell, you can instead specify them all at the same time in the invocation you use for running `git-gloss` — like this: +> +> ``` +> OTHER_OTHER_REPO=LadybirdBrowser/ancient-history OTHER_REPO=SerenityOS/serenity \ +> GREP=/opt/homebrew/bin/ggrep GIT=/opt/homebrew/bin/git ./git-gloss +>``` + +#### `GIT` + +You can use this to specify a path to a different `git` binary — for instance, in the case where you have multiple different `git` versions on your system; example: + +``` +export GIT=/opt/homebrew/bin/git +``` + +> [!NOTE] +> Because `git-gloss` calls the `git notes` command with the `--no-separator` option — which was added in git [version 2.42+](https://stackoverflow.com/a/76633969/) — the git version you use with `git-gloss` must be version 2.42 or later. + +#### `GREP` + +You can use this to specify a path to any grep-compatible binary on your system; for instance, to avoid using the Apple-provided `grep` on macOS; example: + +``` +export GREP=/opt/homebrew/bin/ggrep +``` + +> [!IMPORTANT] +> On macOS in particular, [GNU grep](https://apple.stackexchange.com/a/193300) — rather than than the Apple-provided `grep` — is recommended, for performance reasons; example: +> +> ``` +> brew install grep +> ``` + +#### `GH_THROTTLE` + +If you’re getting 403 responses from the GitHub API due to exceeding the API’s 5000-requests-per-hour [rate limit](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api), you can use this to specify a number of seconds (or a fraction of a second) that `git-gloss` will “sleep” between processing each commit (and thus make fewer requests per minute, and fewer requests per hour). + +``` +export GH_THROTTLE=1 +``` + +#### `OTHER_REPO` + +You can use this to specify an `[owner]/[repo]` repo other than the current repo; e.g., a repo the current repo shares part of its commit history with (because the current repo was created from an older repo); example: + +``` +export OTHER_REPO=SerenityOS/serenity +``` + +If you specify an `OTHER_REPO` value, then if `git-gloss` can’t find any pull request for a particular commit in the current repo, it will then look for a pull request in the repo you specified in the `OTHER_REPO` value. + +> [!WARNING] +> Setting an `OTHER_REPO` value causes `git-commit` to process commit histories from multiple repos, and will likely make `git-gloss` take significantly longer to finish (because it causes 2 additional GitHub API calls for each commit — on top of the 4 GitHub API calls that `git-gloss` already makes for each commit). + +#### `OTHER_OTHER_REPO` + +You can use this in addition to `OTHER_REPO` — if you have a third repo with a shared history; example: + + ``` + export OTHER_OTHER_REPO=LadybirdBrowser/ancient-history + ``` + +> [!WARNING] +> Setting an `OTHER_OTHER_REPO` value will likely make `git-gloss` take significantly longer to finish. + +### Add a “git gloss” command + +Clone the `git-gloss` repo and add its directory to your `$PATH`: + + ```bash + git clone https://github.com/sideshowbarker/git-gloss.git + cd git-gloss + echo export PATH=\"$PATH:$PWD\" >> ~/.bash_profile + ``` + + Now you can just type `git gloss` in any repo/clone directory, to add notes to the logs for that repo. + +### Notes + +You can see how much space your notes tree is taking up by running this command: + +``` +git ls-tree -r $(git rev-parse refs/notes/commits) \ + | awk '{print $3}' | git cat-file --batch-check='%(objectsize:disk)' \ + | awk '{s+=$1} END {printf "%.2f MB\n", s / 1048576}' +``` diff --git a/git-gloss b/git-gloss new file mode 100755 index 0000000..1f3b126 --- /dev/null +++ b/git-gloss @@ -0,0 +1,212 @@ +#!/bin/bash + +GIT=${GIT:-git} +GREP=${GREP:-grep} +GH_THROTTLE=${GH_THROTTLE:-.1} + +error() { + echo " ❌ error: $*" +} + +remoteURLproperty=remote.origin.url +if [ -n "$(GIT config --get remote.upstream.url)" ]; then + remoteURLproperty=remote.upstream.url +fi + +repoURL=$(GIT config --get $remoteURLproperty | sed -r \ + 's/.*(\@|\/\/)(.*)(\:|\/)([^:\/]*)\/([^\/]*)\.git/https:\/\/\2\/\4\/\5/') + +startRepo=$(echo "$repoURL" | rev | cut -d '/' -f-1 | rev) +startOwner=$(echo "$repoURL" | rev | cut -d '/' -f2 | rev) +if [[ $repoURL == *"github"* && -z "$startRepo" ]]; then + echo + echo -n -e \ + "error: This tool must be run from within a clone " >&2 + echo -e "of a GitHub repo. Stopping." >&2 + exit 1; +fi + +otherRepo=$(echo "$OTHER_REPO" | rev | cut -d '/' -f-1 | rev) +otherOwner=$(echo "$OTHER_REPO" | rev | cut -d '/' -f2 | rev) +otherOtherRepo=$(echo "$OTHER_OTHER_REPO" | rev | cut -d '/' -f-1 | rev) +otherOtherOwner=$(echo "$OTHER_OTHER_REPO" | rev | cut -d '/' -f2 | rev) + +if ! [[ -x "$(command -v jq)" ]]; then + echo + echo -e \ + "error: You must have jq installed in order to use this tool." >&2 + exit 1; +fi +allCommits=$(mktemp) +commitsWithNotes=$(mktemp) +commitsWithoutNotes=$(mktemp) +$GIT log --pretty=format:"%H" > "$allCommits" +$GIT notes list | xargs | tr " " "\n" > "$commitsWithNotes" +if [[ -s "$commitsWithNotes" ]]; then + $GREP -Fxv -f "$commitsWithNotes" "$allCommits" > "$commitsWithoutNotes" +else + commitsWithoutNotes=$allCommits +fi +totalCommitsCount=$(wc -l < "$commitsWithoutNotes" | xargs) +if [ "$totalCommitsCount" -eq "0" ]; then + commitsWithoutNotes=$allCommits +fi +currentCommitNumber=0 + +addNote() { + sleep "$GH_THROTTLE" + ((currentCommitNumber++)) + printf "%${#totalCommitsCount}d" "$currentCommitNumber" + echo -n "/$totalCommitsCount " + shortCommitHash=$(git rev-parse --short "$1") + echo -n "$shortCommitHash " + commit=$(gh api "/repos/$owner/$repo/commits/$1" 2>/dev/null) + if [[ $(echo "$commit" | jq ".status" 2>/dev/null) == '"422"' ]]; then + echo -n "https://github.com/$owner/$repo/commit/$shortCommitHash" + error "failed to fetch commit from GitHub; re-trying" + addNote "$1" + fi + pullRequest=$(gh api "/repos/$owner/$repo/commits/$1/pulls" 2>/dev/null) + if [[ "$pullRequest" == "[]" + || $(echo "$pullRequest" \ + | jq ".status" 2>/dev/null) == '"422"' ]]; then + if [[ -n "$otherRepo" ]]; then + otherCommit=$(gh api \ + "/repos/$otherOwner/$otherRepo/commits/$1" 2>/dev/null) + if [[ $(echo "$otherCommit" \ + | jq ".status" 2>/dev/null) != '"422"' ]]; then + pullRequest=$(gh api \ + "/repos/$otherOwner/$otherRepo/commits/$1/pulls" 2>/dev/null) + owner="$otherOwner"; repo="$otherRepo" + elif [[ -n "$otherOtherRepo" ]]; then + otherOtherCommit=$(gh api \ + "/repos/$otherOtherOwner/$otherOtherRepo/commits/$1" 2>/dev/null) + if [[ $(echo "$otherOtherCommit" \ + | jq ".status" 2>/dev/null) != '"422"' ]]; then + pullRequest=$(gh api \ + "/repos/$otherOtherOwner/$otherOtherRepo/commits/$1/pulls" 2>/dev/null) + owner="$otherOtherOwner"; repo="$otherOtherRepo" + fi + fi + fi + fi + echo -n "https://github.com/$owner/$repo/commit/$shortCommitHash" + author=$(echo "$commit" | jq ".author.login" \ + || error "$shortCommitHash failed to get author name") + author=$(echo "$author" | tr -d '"') + authorEmail=$(echo "$commit" | jq ".commit.author.email" \ + || error "$shortCommitHash failed to get author email") + authorEmail=$(echo "$authorEmail" | tr -d '"') + authorFirstCommit=$(git log \ + --format="%H" --no-use-mailmap --author="$authorEmail" | tail -1) + if [[ "$authorFirstCommit" == "$1" ]]; then + $GIT notes append --no-separator \ + -m "Author: https://github.com/$author 🔰" "$1" + else + $GIT notes append --no-separator \ + -m "Author: https://github.com/$author" "$1" + fi + $GIT notes append --no-separator \ + -m "Commit: https://github.com/$owner/$repo/commit/$shortCommitHash" "$1" + if [[ "$pullRequest" == "[]" + || $(echo "$pullRequest" | jq ".status" 2>/dev/null) == '"422"' ]]; then + echo " ✅" + return 0 + fi + prNumber=$(echo "$pullRequest" | jq '.[0].number' \ + || error "failed to get PR number") + if [[ -n "$prNumber" && "$prNumber" != "null" ]]; then + $GIT notes append --no-separator \ + -m "Pull-request: https://github.com/$owner/$repo/pull/$prNumber" "$1" + # shellcheck disable=SC2016 + issues=$(gh api graphql \ + -F owner="$owner" -F repo="$repo" -F pr="$prNumber" -f query=' + query ($owner: String!, $repo: String!, $pr: Int!) { + repository(owner: $owner, name: $repo) { + pullRequest(number: $pr) { + closingIssuesReferences(first: 100) { + nodes { + number + } + } + } + } + }' --jq \ + '.data.repository.pullRequest.closingIssuesReferences.nodes[].number' \ + || (error "failed to fetch issues from GitHub; re-trying"; \ + $GIT notes remove "$1"; \ + addNote "$1") + ) + if [[ -n "$issues" ]]; then + for issue in $issues; do + $GIT notes append --no-separator \ + -m "Issue: https://github.com/$owner/$repo/issues/$issue" "$1" + done; + fi + reviewerDataFile=$(mktemp) + reviews=$(gh api \ + "/repos/$owner/$repo/pulls/$prNumber/reviews" 2>/dev/null) + if [[ $(echo "$reviews" | jq ".status" 2>/dev/null) == '"404"' ]]; then + error "failed to fetch reviews from GitHub; re-trying" + $GIT notes remove "$1" + addNote "$1" + fi + reviews=$(echo "$reviews" | jq "sort_by(.state)") + if [[ -n "$reviews" ]]; then + echo "$reviews" | jq -c -r '.[]' | while read -r review; do + reviewer=$(echo "$review" | jq -r ".user.login" \ + || error "failed to get reviewer name") + state=$(echo "$review" | jq -r ".state" \ + || error "failed to get review state") + association=$(echo "$review" | jq -r ".author_association" \ + || error "failed to get reviewer association") + case "$association" in + OWNER | MEMBER | CONTRIBUTOR | COLLABORATOR | OUTSIDE_COLLABORATOR) + if [[ -z $($GREP "$reviewer" "$reviewerDataFile") \ + && "$reviewer" != "$author" + && "github-actions[bot]" != "$reviewer" ]]; then + if [[ "$state" == "APPROVED" ]]; then + echo "Reviewed-by: https://github.com/$reviewer ✅" \ + >> "$reviewerDataFile"; + else + echo "Reviewed-by: https://github.com/$reviewer" >> \ + "$reviewerDataFile"; + fi + fi + esac + done + reviewerData=$(sort "$reviewerDataFile" | uniq) + echo "$reviewerData" > "$reviewerDataFile" + [[ -s "$reviewerDataFile" ]] && while read -r line; do + [[ -n "$line" ]] && $GIT notes append --no-separator -m "$line" "$1" + done < "$reviewerDataFile" + fi + fi + echo " ✅" +} +if [[ -z "$*" ]]; then + echo "Found $totalCommitsCount commits to process." + echo + while read -r sha; do + owner=$startOwner + repo=$startRepo + if [[ -z $($GIT notes show "$sha" 2>/dev/null) ]]; then + trap "" SIGINT # On ^C, wait until addNote returns before exiting. + addNote "$sha" + trap - SIGINT + fi + done < "$commitsWithoutNotes" +else + totalCommitsCount=$# + echo "Found $totalCommitsCount commits to process." + echo + for sha in "$@"; do + owner=$startOwner + repo=$startRepo + if [[ -z $($GIT notes show "$sha" 2>/dev/null) ]]; then + trap "" SIGINT # On ^C, wait until addNote returns before exiting. + addNote "$sha" + trap - SIGINT + fi + done +fi