From 1d8ec69ed3253d1daae0e11e8b8b407278173689 Mon Sep 17 00:00:00 2001 From: calchiwo Date: Thu, 7 May 2026 16:24:23 +0100 Subject: [PATCH 1/2] docs: move detailed installation docs out of README --- README.md | 176 +++++++------------------------------------ docs/INSTALLATION.md | 147 ++++++++++++++++++++++++++++++++++++ 2 files changed, 176 insertions(+), 147 deletions(-) create mode 100644 docs/INSTALLATION.md diff --git a/README.md b/README.md index 3661370..125b17a 100644 --- a/README.md +++ b/README.md @@ -31,152 +31,57 @@ ExplainThisRepo analyzes real project signals; configs, entrypoints, manifests, ## Installation -### Option 1: install with pip (Python source version): +ExplainThisRepo supports multiple installation methods: -Requirements: Python 3.9+ +- pip (Python package) +- npm (prebuilt native binaries) +- .NET global tool +- standalone binaries + +### Quick install + +#### pip ```bash pip install explainthisrepo -explainthisrepo owner/repo - -# explainthisrepo . -# explainthisrepo ./path/to/directory -# explainthisrepo ./path/to/file.py -# explainthisrepo owner/repo/path/to/file.py -# explainthisrepo owner/repo/path/to/directory ``` Alternatively, ```bash pipx install explainthisrepo -explainthisrepo owner/repo ``` -After installation, use any of the available commands: - -```bash -explainthisrepo owner/repo -explain-this-repo owner/repo -etr owner/repo -``` - -To install support for specific models: - -```bash -pip install explainthisrepo[gemini] -pip install explainthisrepo[openai] -pip install explainthisrepo[anthropic] -pip install explainthisrepo[groq] -``` - -Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`, `torvalds/linux`). - -### Option 2: Install with npm (prebuilt binary, no Python install required) - -Install globally and use forever: +#### npm ```bash npm install -g explainthisrepo -explainthisrepo owner/repo ``` -
-
-
-explainthisrepo .
-explainthisrepo ./path/to/directory
-explainthisrepo ./path/to/file.py
-explainthisrepo owner/repo/path/to/file.py
-explainthisrepo owner/repo/path/to/directory
-
-
-
- -Or without install: +#### .NET ```bash -npx explainthisrepo owner/repo +dotnet tool install -g ExplainThisRepo ``` -
-
-
-npx explainthisrepo .
-npx explainthisrepo ./path/to/directory
-npx explainthisrepo ./path/to/file.py
-npx explainthisrepo owner/repo/path/to/file.py
-npx explainthisrepo owner/repo/path/to/directory
-
-
-
- -### Option 3: Install with .NET (C# Global Tool) - -Requirements: .NET 8, 9, or 10: +#### Run ```bash -dotnet tool install -g explainthisrepo explainthisrepo owner/repo - -# dotnet tool install -g explainthisrepo -# explainthisrepo . ``` -## How it works - -ExplainThisRepo has one core engine and multiple distribution layers. - -- Python is the source of truth for analysis, prompts, providers, and output -- npm ships the Node launcher plus prebuilt native binaries -- .NET ships the same native binary as a global tool and publishes to NuGet -- GitHub Releases publish the standalone binaries - -The Node and .NET layers are launchers only. They detect the current platform, locate the matching bundled binary, and execute it with the user’s arguments. - -The same native binary is what actually performs the work. - -## Distribution model - -ExplainThisRepo is shipped in multiple ways: - -- `pip` for Python users -- `npm` for Node users -- `dotnet tool` for .NET users -- standalone binaries for direct download - -All of them run the same core Python engine compiled into native binaries. - -### Option 4: Download standalone binary - -Prebuilt standalone binaries are available for macOS, Linux, and Windows. - -> Standalone binaries require no Python or Node installation and run as a single executable. - -Download the latest release: [ExplainThisRepo latest releases](https://github.com/calchiwo/ExplainThisRepo/releases/latest) - -Or install directly: -
-macOS +After installation, use any of the available commands: ```bash -curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-darwin-arm64 -o explainthisrepo -chmod +x explainthisrepo +explainthisrepo owner/repo +explain-this-repo owner/repo +etr owner/repo ``` -Linux - -```bash -curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-linux-x64 -o explainthisrepo -chmod +x explainthisrepo -``` +Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`, `torvalds/linux`). -Windows (PowerShell) -```powershell -curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-win-x64.exe -o explainthisrepo.exe -``` -
+For full installation instructions, platform-specific notes, standalone binaries, Termux support, and advanced setup: [docs/INSTALLATION.md](https://github.com/calchiwo/ExplainThisRepo/blob/main/docs/INSTALLATION.md) ## Configuration @@ -198,6 +103,15 @@ explainthisrepo init > For details about how initialization works, see [docs/INIT.md](https://github.com/calchiwo/ExplainThisRepo/blob/main/docs/INIT.md). +To install support for specific models: + +```bash +pip install explainthisrepo[gemini] +pip install explainthisrepo[openai] +pip install explainthisrepo[anthropic] +pip install explainthisrepo[groq] +``` + ## GitHub token Access (Private Repos & Rate Limits) ExplainThisRepo supports GitHub authentication for: @@ -541,39 +455,7 @@ Termux has some environment limitations that can make `pip install explainthisre However, it's recommended you install using: ```bash -pip install --user -U explainthisrepo -``` - -Make sure your user bin directory is on your PATH: - -```bash -export PATH="$HOME/.local/bin:$PATH" -``` - -> Tip: Add the PATH export to your `~/.bashrc` or `~/.zshrc` so it persists. - -### Alternative (No PATH changes) - -If you do not want to modify PATH, you can run ExplainThisRepo as a module: - -```bash -python -m explain_this_repo owner/repo -``` - -### Gemini support on Termux - -Installing Gemini support may require building Rust-based dependencies on Android, which can take time on first install: - -```bash -pip install --user -U "explainthisrepo[gemini]" -``` - -For mobile environments like Termux where compiling Python dependencies can be slow, -you can also run ExplainThisRepo using the Node.js version: - -```bash -npx explainthisrepo owner/repo -``` +pip ## Philosophy diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md new file mode 100644 index 0000000..bdcacfc --- /dev/null +++ b/docs/INSTALLATION.md @@ -0,0 +1,147 @@ +# Installation + +### Option 1: install with pip (Python source version): + +Requirements: Python 3.9+ + +```bash +pip install explainthisrepo +explainthisrepo owner/repo + +# explainthisrepo . +# explainthisrepo ./path/to/directory +# explainthisrepo ./path/to/file.py +# explainthisrepo owner/repo/path/to/file.py +# explainthisrepo owner/repo/path/to/directory +``` + +Alternatively, + +```bash +pipx install explainthisrepo +explainthisrepo owner/repo +``` + +After installation, use any of the available commands: + +```bash +explainthisrepo owner/repo +explain-this-repo owner/repo +etr owner/repo +``` + +To install support for specific models: + +```bash +pip install explainthisrepo[gemini] +pip install explainthisrepo[openai] +pip install explainthisrepo[anthropic] +pip install explainthisrepo[groq] +``` + +Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`, `torvalds/linux`). + +### Option 2: Install with npm (prebuilt binary, no Python install required) + +Install globally and use forever: + +```bash +npm install -g explainthisrepo +explainthisrepo owner/repo +``` + +
+
+
+explainthisrepo .
+explainthisrepo ./path/to/directory
+explainthisrepo ./path/to/file.py
+explainthisrepo owner/repo/path/to/file.py
+explainthisrepo owner/repo/path/to/directory
+
+
+
+ +Or without install: + +```bash +npx explainthisrepo owner/repo +``` + +
+
+
+npx explainthisrepo .
+npx explainthisrepo ./path/to/directory
+npx explainthisrepo ./path/to/file.py
+npx explainthisrepo owner/repo/path/to/file.py
+npx explainthisrepo owner/repo/path/to/directory
+
+
+
+ +### Option 3: Install with .NET (C# Global Tool) + +Requirements: .NET 8, 9, or 10: + +```bash +dotnet tool install -g ExplainThisRepo +explainthisrepo owner/repo + +# dotnet tool install -g ExplainThisRepo +# explainthisrepo . +``` + +## How it works + +ExplainThisRepo has one core engine and multiple distribution layers. + +- Python is the source of truth for analysis, prompts, providers, and output +- npm ships the Node launcher plus prebuilt native binaries +- .NET ships the same native binary as a global tool and publishes to NuGet +- GitHub Releases publish the standalone binaries + +The Node and .NET layers are launchers only. They detect the current platform, locate the matching bundled binary, and execute it with the user’s arguments. + +The same native binary is what actually performs the work. + +## Distribution model + +ExplainThisRepo can be installed in multiple ways: + +- `pip` for Python users +- `npm` for Node users +- `dotnet tool` for .NET users +- standalone binaries for direct download + +All of them run the same core Python engine compiled into native binaries. + +### Option 4: Download standalone binary + +Prebuilt standalone binaries are available for macOS, Linux, and Windows. + +> Standalone binaries require no Python or Node installation and run as a single executable. + +Download the latest release: [ExplainThisRepo latest releases](https://github.com/calchiwo/ExplainThisRepo/releases/latest) + +Or install directly: + +macOS + +```bash +curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-darwin-arm64 -o explainthisrepo +chmod +x explainthisrepo +``` + +Linux + +```bash +curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-linux-x64 -o explainthisrepo +chmod +x explainthisrepo +``` + +Windows (PowerShell) + +```powershell +curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-win-x64.exe -o explainthisrepo.exe +``` From 0b7d9263ec7e5ddc560f0688ecd555df8bbffc63 Mon Sep 17 00:00:00 2001 From: calchiwo Date: Thu, 7 May 2026 16:49:45 +0100 Subject: [PATCH 2/2] docs: move Termux setup notes into dedicated docs page --- README.md | 9 +++------ docs/TERMUX.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 6 deletions(-) create mode 100644 docs/TERMUX.md diff --git a/README.md b/README.md index 125b17a..5a8249b 100644 --- a/README.md +++ b/README.md @@ -448,14 +448,11 @@ Use the `--doctor` flag to verify the environment, network connectivity, and API explainthisrepo --doctor ``` -## Termux (Android) install notes +## Termux (Android) -Termux has some environment limitations that can make `pip install explainthisrepo` fail to create the `explainthisrepo` command in `$PREFIX/bin`. +ExplainThisRepo supports Termux on Android. -However, it's recommended you install using: - -```bash -pip +For installation notes, PATH setup, Gemini support, and mobile-specific recommendations: see [docs/TERMUX.md](https://github.com/calchiwo/ExplainThisRepo/blob/main/docs/TERMUX.md) ## Philosophy diff --git a/docs/TERMUX.md b/docs/TERMUX.md new file mode 100644 index 0000000..a236477 --- /dev/null +++ b/docs/TERMUX.md @@ -0,0 +1,42 @@ +# Termux (Android) setup notes + +ExplainThisRepo supports running inside the Termux environments on Android devices + +Termux has some environment limitations that can make `pip install explainthisrepo` fail to create the `explainthisrepo` command in `$PREFIX/bin`. + +However, it's recommended you install using: + +```bash +pip install --user -U explainthisrepo +``` + +Make sure your user bin directory is on your PATH: + +```bash +export PATH="$HOME/.local/bin:$PATH" +``` + +> Tip: Add the PATH export to your `~/.bashrc` or `~/.zshrc` so it persists. + +### Alternative (No PATH changes) + +If you do not want to modify PATH, you can run ExplainThisRepo as a module: + +```bash +python -m explain_this_repo owner/repo +``` + +### Gemini support on Termux + +Installing Gemini support may require building Rust-based dependencies on Android, which can take time on first install: + +```bash +pip install --user -U "explainthisrepo[gemini]" +``` + +For mobile environments like Termux where compiling Python dependencies can be slow, +you can also run ExplainThisRepo using the Node.js version: + +```bash +npx explainthisrepo owner/repo +``` \ No newline at end of file