jarred-sumner / git-peek

git repo to local editor instantly

git-peek

git peek is the fastest way to open a remote git repository in your local text editor.

Use it when you want to browse or search other people's code with your own editor.

Installation:

Homebrew:

brew install jarred-sumner/git-peek/git-peek

For Windows and Linux, install from npm directly:

npm install -g @jarred/git-peek

1-click "Peek" button for GitHub:

• Download peek for Chrome
• Download peek for Firefox

Usage:

git peek https://github.com/ylukem/pin-go
git peek https://github.com/jarred-sumner/atbuild
git peek https://github.com/facebook/react/pull/20790
git peek hanford/trends
git peek react
git peek https://github.com/jarred-sumner/fastbench.dev/tree/main/
git peek https://github.com/evanw/esbuild/blob/master/lib/common.ts

Pass git peek a git repository or a github link, and it will quickly fetch and open it in your local editor. It stores the repository in a temporary directory and deletes it when you close the editor or git peek.

It's fast.

❯ git peek https://github.com/nodejs/node/blob/master/lib/dgram.js
⏳ Extracting repository to temp folder...
💻 Launched editor in 0.20s

If you paste a link to a pull request on GitHub, it will open it quickly:

❯ git peek https://github.com/facebook/react/pull/20790
💻 Launched editor in 0.13s
⏳ Extracting repository to temp folder...
💿 Finished downloading repository!

Much faster than cloning.

If you don't pass git peek input, it will let you search Github repositories and show trending repositories:

❯ git peek
Search Github repositories:
> Search
❯ iam-abbas/Reddit-Stock-T | Fetch currently trending stocks on Reddit
  codeSTACKr/free-develope | Free Developer Resources
  justjavac/1s             | 天若有情天亦老，我为网站加一秒
  PaddlePaddle/PaddleNLP   | NLP Core Library and Model Zoo based on PaddlePa
  ModernPwner/cicuta_viros |
  jevakallio/vscode-live-f | Run your web app inside VS Code
  getActivity/AndroidCodeS | Android 代码规范文档
  gigantz/react-xpress     | React renderer to build Node.js server

If you type a repository name without the owner (react instead of facebook/react), it will search:

❯ git peek react
Search Github repositories:
> react
❯ facebook/react           | A declarative, efficient, and flexible JavaScrip
  typescript-cheatsheets/r | Cheatsheets for experienced React developers get
  duxianwei520/react       |  React+webpack+redux+ant design+axios+less全家桶后台管
  discountry/react         | React docs in Chinese | React 中文文档翻译
  Cathy0807/react          | 京东首页构建
  react-redux-antd-es6/rea | 基于react的企业后台管理开发框架
  HackYourFuture/React     | This repository contains all the material for th
  geist-org/react          | Modern and minimalist React UI library.

If you paste a link to a file on GitHub, it will quickly open the file in your local editor:

❯ git peek https://github.com/Jarred-Sumner/git-peek/blob/main/src/index.ts
💻 Launched editor in 0.39s
⏳ Extracting repository to temp folder...
💿 Finished downloading repository!

❯ git peek -h
 Quickly preview remote Git repositories in your local editor

  USAGE
    $ git-peek [git link or github link or search query or repository file path]

  EXAMPLES
    git peek https://github.com/evanw/esbuild/blob/master/lib/common.ts
    git peek https://github.com/ylukem/pin-go
    git peek https://github.com/jarred-sumner/atbuild
    git peek hanford/trends
    git peek react

  OPTIONS
    -e, --editor=editor  [default: auto] editor to open with, possible values:
                          auto, code, subl, nvim, vim, vi, code-insiders.
                          By default, it will search $EDITOR. If not found, it
                          will try code, then subl, then vim.

    -r, --register        [default: false] Register the git-peek:// url protocol
                          This allows the "Open" buttons to work on
                          github.com once you\'ve installed the extension. Only
                          supported on macOS and Windows

    -o, --out=           [default: system temp directory] output directory to
                          store repository files in. If youre cloning a large
                          repo and your tempdir is an in-memory storage (/tmp),
                          maybe change this.

    -w, --wait           [default: false] wait to open the editor until the
                          repository finishes downloading. always on for vi.

    --no-keep            [default: false] keep the repository, rather than
                         deleting it.

    -b, --branch         [default: "master"] select a branch/ref to use.
                         if the repository doesn't use master/main,
                         you'll want to set this manually. but it will
                         try to infer from the input by default.

    -d                   [default: false] Ask the GitHub API
                          for the default_branch to clone.

    -h, --help           show CLI help

  ENVIRONMENT VARIABLES:
    $EDITOR: code --wait
    $GITHUB_TOKEN: ********
    .env: ✅ $HOME/.git-peek

  For use with private GitHub repositories, set $GITHUB_TOKEN to a personal
  access token. To persist it, store it in your shell config or the .env shown above.

Private repositories & choosing an editor

To use git-peek with private repositories, set a $GITHUB_TOKEN to a personal access token. If you don't want a global shell $GITHUB_TOKEN, you can set in $HOME/.git-peek.

Its a .env file, so the syntax looks like this:

EDITOR="code"
GITHUB_TOKEN="**********"

You can also save a custom editor this way. So you don't have to add -e vim everytime if $EDITOR is not propagating to the process.

How does this work?

If you pass it a GitHub repository, it fetches a tarball instead of using git and decompresses it while downloading it (streaming). From unscientific benchmarks, this is about 2x faster than cloning. While downloading & decompressing the tarball, it also downloads the specific file linked to (or the README.md) via JSDelivr's CDN. Whichever happens first, it opens in the editor (usually JSDelivr), but it will keep fetching the repo until its complete or the program exits.

If you pass it a git repository rather than a Github url, it does a partial clone instead of doing a full clone.

When your editor closes or you close git peek, it deletes the repository from your computer.

Changelog

1.3.18

• Add support for BBCode on macOS
• Adjust location for the shim that opens git-peek on macOS from extension (thanks @JayBrown)

1.3.14 - 1.3.17

• Fix $EDITOR detection bug

1.3.14

• Auto-detect nvim
• Add /n?vim?/ support for Peek (browser extension) on macoS.

1.3.8 - 1.3.13

• Improve reliability of git peek -r on macOS
• Support skipping JSDelivr requests when we know in advance its a private repository
• Fix the homebrew build

1.3.7

• Fix AbortController polyfill in Node 14.

1.3.6

• Fix windows path bug

1.3.5

• Improve start performance by about 25% via code splitting

1.3.4

• Improve reliability of deleting files on Windows. On POSIX systems, you can delete files when they're in use. Windows will refuse, even if "in use" means, the process' current working directory is set to it but there aren't necessarily files open for it. The fix was to make it so that the current working directory on Windows is the parent directory, and also to tell rimraf to first delete all the files inside the folder and then delete the folder itself. This probably isnt' ideal for performance, maybe there's a more "native" system call for this.
• Fix logs that were supposed to only show up with VERBOSE env var set
• More reliably exit the process when opened from browser extension on Windows. Trying to prevent lots of extraneous subl.exe from showing up

1.3.3

• Add support for GitHub Enterprise! (Thanks @Thau)
• Fix detecting when you closed Visual Studio Code after opening it from git-peek:// (this already worked in the CLI). git-peek should now automatically delete the repository when using the browser extension (when your editor is Visual Studio Code)

1.3.0 - 1.3.2

Windows

• Add Windows support for registering the git-peek:// protocol!! (related: https://github.com/Jarred-Sumner/register-url-windows). This enables 1-click open buttons on GitHub. Run git peek --register
• Add ./bin/git-peek-win32.exe that runs git-peek without the CMD.exe window appearing (source code is in the win32 folder). It just receives git-peek:// URLs, so if you run it by itself, nothing will show up and you'll be kind of confused.

Mac

• Prevent homebrew from running cleanup and auto update when you run git-peek --register. So that it runs faster.
• Prevent the applescript from stealing focus when you click the open button in the browser extension. To use this, you'll have to re-run git-peek --register if you haven't already.

Misc

• Temp folder names now start with the repository@branchOrRef name e.g. esbuild@main, so its clearer what you're looking at in your editor. Its still a long string, but the beginning at least makes more sense now.
• Temp folder names now end in peekautodelete. This will later be used for a git-peek purge command that will automatically delete any folders it finds in the temp directory containing "peekautodelete" incase anything was missed.
• Fix bug where sometimes empty text would appear in your editor when it guessed the default filename wrong. Please open an issue if you see this happen again.
• Will now confirm closing for Sublime Text instead of failing to detect when it closed and then hanging. Sublime Text's --wait CLI argument does not support folders, so it's pretty tough to detect when the user closes Sublime Text without some kind of process monitoring.
• Add sourcemap file because why not
• Made the "Deleted repository" log double check that the repository is no longer there before logging it.

---

• 1.2.2: Prevent process from sticking around longer than necessary if its still extracting the repository when its supposed to close. Add fs.rmSync polyfill

• 1.2.1: Slightly improve reliability & performance of launching the editor (using child_process.spawn instead of using child_process.exec) and allow the AppleScript to launch multiple instances

• 1.2.0: Create a git-peek:// URL handler, so that you can click a link to open a repository in your local editor. Register the URL handler with git peek -r.

• 1.1.37: Add easter egg to search results

• 1.1.36: Add optional -d flag that automatically asks github what the default branch is before cloning instead of guessing its either main or master.

• 1.1.35: Add optional --branch flag so you can choose which branch to clone if its not shown in the url. See #17

• 1.1.34: Fix home directory path resolution on Windows

• 1.1.33: Add precompiled binary for windows in releases script.

• 1.1.32 Add --no-keep flag which skips deleting repositories on exit. Fix support for unknown editors. When the editor is unknown, it asks to confirm deleting the repository.

• 1.1.31: Fix issue where when vim is loaded with a specific file (rather than the repository root dir), it would log text on top of vim.

1.1.30

git-peek now starts 32% faster (delayed loading ink until its used for search)

You can now store $EDITOR and $GITHUB_TOKEN in $HOME/.git-peek. Its a .env file, so the syntax looks like this:

EDITOR="code"
GITHUB_TOKEN="**********"

Removed using the $GITHUB_TOKEN from ~/.hubs/config.

• 1.1.28-29: Fix for Node 12+ #14
• 1.1.27: Added --wait flag which waits to open the editor until the entire repository is downloaded. Added --out flag which changes the temp directory to store files in (see #8)
• 1.1.22-26: Fix windows bug.
• 1.1.21: Add Pull Request support. Now you can use this to quickly read a pull request. For example: git peek https://github.com/facebook/react/pull/20790.
• 1.1.20: Fix bug when using with Fedora
• 1.1.16-1.1.19: trying to get release-it to work
• 1.1.15: Move code-insiders to end of preference list
• 1.1.14: Fix code-insiders and fix passing in editor manually when its subl or code.
• 1.1.13: Use Authorization header instead of access_token query string.
• 1.1.12: When available, also use github access token for fetching tarballs (instead of just search)
• 1.1.11: When available, use github access token for github API requests to enable private repositories to work. To enable this, either set a GITHUB_TOKEN environment variable or if you've installed hub, it will automatically use oauth_token from $HOME/.config/hub. In other words, if you use hub, this should just work by default.
• 1.1.10: Fix vim
• 1.1.9: Fix Windows

Known Bugs

Sublime Text

subl --wait does not support folders, so git-peek is unable to detect when Sublime Text closes. On the CLI, this isn't a problem – it just shows a "Delete Repository Y/n" confirm message, same as other editors.

On the browser extension, I'm not really sure yet what to do about this.

Visual Studio Code doesn't have this problem because passing a directory to --wait correctly waits until the window is closed.

Originally inspired by github1s.com.

git-peek's Issues

Feature Request: Open pull request in editor

I'd like to be able to open a pull request in my editor using git peek -e code https://github.com/facebook/react/pull/20790

Reason: When I'm doing code reviews sometimes it's easier to review the code in my editor and be able to jump around the code without using Github's diff UI.

Additional info:
If you goto the above PR, fetch the last commit, then the archive should be available here https://github.com/facebook/react/archive/34501538a866d51f9ec5a486be8d34f8162ccf7f.zip

Add configuration for default $EDITOR override

I'd like to use WebStorm when running git peek, however my $EDITOR environment is set to vim and I'd prefer to keep it this way because I prefer working in the terminal when working with git for interactive rebases.

I know I currently can overcome this by writing git peek -e webstorm url however it would be nice if I could save a default editor once I set up git peek that I won't have to remember adding the flag each time

brew package

Is it possible to get a brew package published? I've never tried to cook a formula on brew before. Not sure it's even possible with Node.js and git-peek being installed globally.

improve error message for unsupported EDITOR

track something to improve error messaging for unsupported $EDITORs? nvim isn't supported right now, and it isn't clear at all that it doesn't work

Doesn't work with code-insiders

(base) ➜  ~ git peek https://github.com/Jarred-Sumner/git-peek -e code-insiders
💻 Launched editor in 0.16s
⏳ Extracting repository to temp folder...
🗑  Deleted temp repo

On macOS 11.1

Looks fine, but vscode launches like this

(base) ➜  ~ which code-insiders
/usr/local/bin/code-insiders
(base) ➜  ~ code-insiders --version
1.54.0-insider
afd102cbd2e17305a510701d7fd963ec2528e4ea
x64
(base) ➜  ~

No problems so far in vim

TODO: streaming decompress instead of downloading entire zip and then decompressing

Doesn't work on macOS with vim

This is a great idea, thanks.

But it doesn't work on my macOS with Homebrew-installed vim:

[Feature Request] Configurable temp path

Great piece of software, just played with it a bit. Although git-peek nicely cleans up after closing the editor, there's potential for bringing a system down by saving to /tmp by default. On most Linux systems /tmp is mounted as tmpfs, meaning that whatever is dropped there, even temporarily, eats into RAM.

I realize that this doesn't pose (much) problems with relatively small repositories, but I wonder if there's some kind of size limit check before committing to download a huge repo. For example, what if one wants to take a quick peek at what Linus Torvalds is doing in the Linux kernel repo (+4GB)? To avoid this potential pitfall it would be nice to have a user-configurable knob to store temporary files at a different location.

brew install v npm

really cool tool, qq that the README doesn't make clear: is the brew installed version giving me the binary? or is it installing the 20% slower npm version?

URL handler not opening git-peak.app

git peek works fine from the command line, but I can't get the url-handler to work. I determined it's not the Chrome extension either since the git-peek:// url doesn't trigger git-peek in Safari either.

Running an M1 Pro Max on macOS 13.0 (22A380) if that helps. Haven't been able to sort it out. 🤕

If you click it serveral times it will eventually show this:

can support download .git folder ?

.git is meaningful when check history of some code

[WSL] - Doesn't work with code-insiders

Hey great project

I just tried it out on WSL. I have code-insiders but it doesn't find it sadly.

➜  ~ which code-insiders
/mnt/c/Program Files/Microsoft VS Code Insiders/bin/code-insiders

➜  ~ git peek https://github.com/Jarred-Sumner/git-peek
⏳ Extracting repository to temp folder...
💿 Finished downloading repository!
💻 Launched editor in 1.09s
🗑  Deleted temp repo

The above opens Vim.
code-insiders is on my path so im not sure why it doesn't open it up. Im assuming its a WSL issue

Edit:
passing -e code-insiders works, is there a way to set that as the default?

Is there a reason why code is before vim but code-insiders is after? I would expect code-insiders to also be near the front. https://github.com/Jarred-Sumner/git-peek/blob/main/src/index.ts#L15
I can see you made a concious choice to push it to the end here: 8fa612e but this means it will never get picked on WSL because vim will always exist before it. Unless the user sets $EDITOR

Open default GH branch

git-peek seems to open the master branch, but if a repo has a non-master default branch this ends up opening the "wrong" branch, and it's not immediately obvious how to open the "correct" branch.

Take this repo as an example: https://github.com/jdiwnab/OrbitSim

• The default branch is "gh-pages".
• Running git-peek https://github.com/jdiwnab/OrbitSim results in the editor being opened to a very sparse repo, since git-peek is opening https://github.com/jdiwnab/OrbitSim/tree/master.
• This experience doesn't match what we see when landing on https://github.com/jdiwnab/OrbitSim , and made me wonder if git-peek was still in the process of cloning the repo or if there was a bug.

The way to open the default branch is to run git-peek https://github.com/jdiwnab/OrbitSim/tree/gh-pages. But this is a url that needs to be constructed manually, as GH doesn't seem to expose it in the UI: the url for the gh-pages branch is just https://github.com/jdiwnab/OrbitSim

It would be nice if git-peek accepted a "branch" parameter or opened the default branch of the repo.

VS Code does not open on Windows

Node v12.18.4
NPM 6.14.6
Windows 10

λ git-peek.cmd https://github.com/webrtc/samples.git
� Launched editor in 0.26s
Error: Command failed: /c/Users/JamesCote/AppData/Local/Programs/Microsoft VS Code/bin/code --wait "C:\Users\JAMESC~1\AppData\Local\Temp\tmp-10752-xVz6CmmhvAv0" --new-window -g "C:\Users\JAMESC~1\AppData\Local\Temp\tmp-10752-xVz6CmmhvAv0\README.md":0:0
The system cannot find the path specified.

    at ChildProcess.exithandler (child_process.js:303:12)
    at ChildProcess.emit (events.js:315:20)
    at maybeClose (internal/child_process.js:1021:16)
    at Process.ChildProcess._handle.onexit (internal/child_process.js:286:5) 
{
  killed: false,
  code: 1,
  signal: null,
  cmd: '/c/Users/JamesCote/AppData/Local/Programs/Microsoft VS Code/bin/code 
--wait "C:\\Users\\JAMESC~1\\AppData\\Local\\Temp\\tmp-10752-xVz6CmmhvAv0" --new-window -g "C:\\Users\\JAMESC~1\\AppData\\Local\\Temp\\tmp-10752-xVz6CmmhvAv0\\README.md":0:0'
}
Error: Command failed: /c/Users/JamesCote/AppData/Local/Programs/Microsoft VS Code/bin/code --wait "C:\Users\JAMESC~1\AppData\Local\Temp\tmp-10752-xVz6CmmhvAv0" --new-window -g "C:\Users\JAMESC~1\AppData\Local\Temp\tmp-10752-xVz6CmmhvAv0\README.md":0:0
The system cannot find the path specified.

    at ChildProcess.exithandler (child_process.js:303:12)
    at ChildProcess.emit (events.js:315:20)
    at maybeClose (internal/child_process.js:1021:16)
    at Process.ChildProcess._handle.onexit (internal/child_process.js:286:5)

line 12: -S: command not found

C:\Users\Administrator>git peek https://github.com/jarred-sumner/git-peek
C:\Users\Administrator\AppData\Roaming\npm\git-peek: line 12: -S: command not found

Sys: Windows 10, 7

macOS: problems on Big Sur (Intel) & BBEdit

So git-peek didn't work as expected with BBEdit. Config file ~/.git-peek has EDITOR=BBEdit --wait

It was working fine in iTerm, but as soon as I use the Firefox extension via the git-peek app, it failed. What I noticed was the following: the code signature of git-peek.app was broken, and it's not possible to apply a new signature, because git-peek-shim was in the wrong place within the bundle.

So I moved that file to ./Contents/MacOS/git-peek-shim, then changed its editor line to export EDITOR="BBEdit", then changed ./Contents/Resources/Scripts/main.scpt to

on open location this_URL
	try
		set innerCmd to "/Users/USER/Applications/git-peek.app/Contents/MacOS/git-peek-shim " & quoted form of this_URL & " &> /usr/local/var/log/git-peek &"
		do shell script innerCmd
	on error errMsg
		display dialog errMsg
	end try
end open location

i.e. changed the path of the variable innerCmd, whereas "USER" is substituted for my actual username, of course… then code-signed the app again, which finally worked, because git-peek-shim was now in a proper nested location. (Note: a broken signature might cause problems on Big Sur on arm64 macOS.)

Now, running git-peek via the Firefox extension opened BBEdit alright, but after the repo downloaded, it didn't show & was colored red, which in BBEdit means that a file has been deleted, in our case that the repo was deleted immediately after download.

How do I solve this problem?

git-peek via iTerm

git-peek via Firefox extension

Doesn't start on Fedora 33, ZSH, Node 14, yarn

I installed this with yarn global add @jarred/git-peek on Fedora 33 Workstation, in ZSH, Node version v14.15.4 and I get this when I run it, with or without a package name:

~: git-peek Jarred-Sumner/git-peek
/usr/bin/env: ‘node --no-warnings’: No such file or directory
/usr/bin/env: use -[v]S to pass options in shebang lines

Same happens when I install with npm install -g ... instead.

Can I do anything, is this a configuration issue on my side?

Bad credentials?

I just tried this at home, and it failed:

$ git peek https://github.com/git-for-windows/git/pull/3017
Failed to load pull request url: HTTP  401
 {"message":"Bad credentials","documentation_url":"https://docs.github.com/rest"}

Why does it need credentials to begin with?

Folder deleted before editor is closed

Nice project! Just one (for me fatal) issue:

On Windows, with JetBrains Rider (C:\Users\<user>\AppData\Local\JetBrains\Toolbox\apps\Rider\ch-0\203.6682.21\bin\rider64.exe) set as $env:EDITOR, the repo is deleted while it is being loaded.

I assume this is because Rider forks itself away causing git-peek to think that it has been closed.

It also leads to some Error: EPERM: operation not permitted, unlink (...) issues, likely due to Windows' file locking while they are open in Rider.

A simple fix/workaround for this might be something like a --no-delete or --no-close option.

Consider support to recognize repo's language to decide which editor to open

Thanks for such a cool project!

I.E.:

• Rust: emacs
• Go: goland
• Java: intellij
• CPP: vim

But this feature should not break editor search order of course, as described in help command: By default, it will search $EDITOR. If not found, it will try code, then subl, then vim. i.e.: search order: goland -> vim -> subl

My current workaround is that I currently take a look at what language is used and set a custom $EDITOR variable just before peek it: EDITOR=clion git peek https://github.com/ylukem/pin-go

rmSync is not a function

I get this stack trace on Windows:

$ git peek https://github.com/git-for-windows/git/pull/3017
 Extracting repository to temp folder...
💻 Launched editor in 0.89s
 Finished downloading repository!
🗑  Deleted temp repo
TypeError: u3.default.rmSync is not a function
    at uE (C:\Users\me\AppData\Roaming\npm\node_modules\@jarred\git-peek\bin\git-peek:497:846)
    at s3.run (C:\Users\me\AppData\Roaming\npm\node_modules\@jarred\git-peek\bin\git-peek:528:2695)
    at processTicksAndRejections (internal/process/task_queues.js:97:5)
TypeError: u3.default.rmSync is not a function
    at uE (C:\Users\me\AppData\Roaming\npm\node_modules\@jarred\git-peek\bin\git-peek:497:846)
    at s3.run (C:\Users\me\AppData\Roaming\npm\node_modules\@jarred\git-peek\bin\git-peek:528:2695)
    at processTicksAndRejections (internal/process/task_queues.js:97:5)

That's with

$ node -v
v12.16.2

Is it possible that

git-peek/src/index.ts

Line 99 in 885e324

fs.rmSync(instance.destination, {

should use await fs.promises.rm() instead (of course, doExit() would then have become async and all the call sites, including this one would have to be adjusted).

Pre-compiled `brew/git-peek` bloats the repository unnecessarily

Cloning this repository is pretty expensive. git sizer says this:

$ git sizer
Processing blobs: 165
Processing trees: 121
Processing commits: 62
Matching commits to trees: 62
Processing annotated tags: 10
Processing references: 13
| Name                         | Value     | Level of concern               |
| ---------------------------- | --------- | ------------------------------ |
| Biggest objects              |           |                                |
| * Blobs                      |           |                                |
|   * Maximum size         [1] |  74.1 MiB | *******                        |

[1]  cb3591f1d9a97e7f816927a30e91c101c484091d (refs/heads/main:brew/git-peek)

A 74.1 megabyte blob... Unfortunately, this is now part of tagged releases, so it cannot easily be removed. But maybe it can be deleted from the tip revision, and a .gitignore could be installed to prevent it from being added again (I see that bbe4e91 tried to delete it but it came back nevertheless)?