README.md (7285B)
1 # Githrun 2 3 Githrun is a versatile command-line tool and VS Code extension that enables you to execute, explore, and install Python scripts directly from GitHub and Gists. It streamlines remote execution by handling dependencies, private repositories, and local tool installation. 4 5 [](https://pypi.org/project/githrun/) [](https://pypi.org/project/githrun/) [](https://github.com/notamitgamer/githrun/blob/main/LICENSE) [](https://pepy.tech/project/githrun) [](https://github.com/notamitgamer/githrun/commits/main) [](https://github.com/notamitgamer/githrun/graphs/contributors) 6 7 --- 8 9 # VS Code Extension 10 11 ## Extension Installation & Setup 12 13 ### 1. Install the Extension 14 * **Marketplace:** Search for "Githrun" in the VS Code Extensions view and click Install. 15 * **Manual:** If installing from a VSIX file, go to Extensions -> ... -> Install from VSIX. 16 17 ### 2. Install the Core CLI (Required) 18 This extension acts as a bridge to the Githrun command-line tool. You **must** have the Githrun CLI installed on your system. 19 20 Open your terminal and run: 21 22 ```bash 23 pip install githrun 24 ``` 25 26 ## Extension Features & Usage 27 28 ### CodeLens Integration 29 The extension automatically scans Markdown, Python, and Text files for GitHub or Gist URLs. 30 * **Action:** Look for the "Run with Githrun" link appearing above any detected URL. 31 * **Click:** Clicking the link opens a terminal and executes the script immediately. 32 33 ### Context Menu 34 * **Action:** Highlight any GitHub URL in your editor. 35 * **Click:** Right-click the selection and choose **Githrun: Run Selected Text**. 36 37 ### Command Palette 38 * **Action:** Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac). 39 * **Command:** Type `Githrun: Run from URL...` and paste your target link into the input box. 40 41 ## Extension Settings 42 The extension attempts to automatically detect your Githrun installation. 43 * It first checks for `githrun` in your global PATH. 44 * If not found, it tries `python -m githrun` (or `python3` on Mac/Linux). 45 46 --- 47 48 ## Features 49 50 * **Remote Execution**: Run scripts from GitHub or Gist URLs instantly. 51 * **Auto-Dependency Management**: Automatically creates temporary virtual environments and installs missing packages using the `--auto-install` flag. 52 * **Private Repo Access**: Authenticate securely with GitHub tokens to access private code and increase API rate limits. 53 * **Bookmarks**: Save long URLs as short aliases (e.g., `githrun run clean-db`). 54 * **Tool Installation**: Install remote scripts as permanent local CLI commands available in your system path. 55 * **Recursive Downloads**: Download entire folders or specific sub-directories from a repository. 56 * **Interactive Search**: Search for files in a repo and run them immediately from the results. 57 * **Smart Caching**: Caches API responses to speed up repeated searches and reduce API usage. 58 59 --- 60 61 ## CLI Usage 62 63 ### 1. Run Remote Code 64 Execute a script directly from a URL. 65 66 **Basic Execution:** 67 ```bash 68 githrun run [https://github.com/user/repo/blob/main/script.py](https://github.com/user/repo/blob/main/script.py) 69 ``` 70 71 **Run Gists:** 72 ```bash 73 githrun run [https://gist.github.com/user/1234567890abcdef](https://gist.github.com/user/1234567890abcdef) 74 ``` 75 76 **Auto-Install Dependencies:** 77 If a remote script requires packages you do not have installed (e.g., pandas, requests), use this flag to run it in an isolated environment: 78 ```bash 79 githrun run [https://github.com/user/repo/blob/main/data.py](https://github.com/user/repo/blob/main/data.py) --auto-install 80 ``` 81 82 **Inspect Code:** 83 View the source code with syntax highlighting before running it (Safety Check): 84 ```bash 85 githrun run [https://github.com/user/repo/blob/main/script.py](https://github.com/user/repo/blob/main/script.py) --inspect 86 ``` 87 88 ### 2. Authentication (Private Repos & Rate Limits) 89 GitHub limits unauthenticated requests to 60 per hour. Login to increase this limit to 5,000 and access private repositories. 90 91 ```bash 92 githrun login ghp_YourPersonalAccessToken... 93 ``` 94 *The token is stored securely in `~/.githrun/config.json`.* 95 96 ### 3. Bookmarks 97 Stop copy-pasting long URLs. Save them once, run them anywhere. 98 99 **Add a Bookmark:** 100 ```bash 101 githrun bookmark add clean-db [https://github.com/user/repo/blob/main/utils/cleanup.py](https://github.com/user/repo/blob/main/utils/cleanup.py) 102 ``` 103 104 **Run a Bookmark:** 105 ```bash 106 githrun run clean-db 107 ``` 108 109 **List Bookmarks:** 110 ```bash 111 githrun bookmark list 112 ``` 113 114 ### 4. Install as a Tool 115 Turn a remote Python script into a command you can run from anywhere in your terminal. 116 117 ```bash 118 githrun install [https://github.com/user/repo/blob/main/my-tool.py](https://github.com/user/repo/blob/main/my-tool.py) --name mytool 119 ``` 120 121 * **Windows:** Creates a `.bat` file in `~/.githrun/bin`. 122 * **Linux/Mac:** Creates an executable shim in `~/.githrun/bin`. 123 * *Note: You must add `~/.githrun/bin` to your system PATH.* 124 125 ### 5. Find & Search 126 Search for files inside a remote repository without cloning it. 127 128 ```bash 129 # Search for files containing "config" 130 githrun find [https://github.com/user/repo](https://github.com/user/repo) "config" 131 ``` 132 *This command is interactive. You can select a result number to run it immediately.* 133 134 ### 6. Download Files & Folders 135 Download artifacts to your local machine. 136 137 **Download a single file:** 138 ```bash 139 githrun download [https://github.com/user/repo/blob/main/script.py](https://github.com/user/repo/blob/main/script.py) 140 ``` 141 142 **Download a specific folder (Recursive):** 143 ```bash 144 githrun download [https://github.com/user/repo/tree/main/src/utils](https://github.com/user/repo/tree/main/src/utils) --output ./local_utils 145 ``` 146 147 ### 7. Show Folder Contents 148 List files in a remote directory to understand the structure. 149 150 ```bash 151 githrun show [https://github.com/user/repo/tree/main/src](https://github.com/user/repo/tree/main/src) 152 ``` 153 154 --- 155 156 ## Python API Usage 157 158 You can use Githrun inside your own Python scripts. 159 160 ```python 161 import githrun 162 163 # 1. Search a repository 164 results = githrun.search_repository("[https://github.com/user/repo](https://github.com/user/repo)", "test") 165 for item in results: 166 print(item['path'], item['raw_url']) 167 168 # 2. Download a file 169 githrun.download_file("[https://github.com/user/repo/blob/main/script.py](https://github.com/user/repo/blob/main/script.py)", output_path="script.py") 170 171 # 3. Download a full folder 172 githrun.download_folder("[https://github.com/user/repo/tree/main/src](https://github.com/user/repo/tree/main/src)") 173 174 # 4. Execute code programmatically 175 exit_code = githrun.execute_remote_code("[https://github.com/user/repo/blob/main/script.py](https://github.com/user/repo/blob/main/script.py)", args=["--verbose"]) 176 ``` 177 178 --- 179 180 ## Configuration 181 182 Githrun stores configuration and cache files in your home directory: 183 184 * **Config:** `~/.githrun/config.json` (Tokens, Bookmarks) 185 * **Cache:** `~/.githrun/cache/` (API responses) 186 * **Binaries:** `~/.githrun/bin/` (Installed tools) 187 188 ## License 189 190 This project is licensed under the MIT License.