From 29c153ee9e641facdf21a757144ec8cdcf0c69d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20Farkas?= Date: Thu, 18 Sep 2025 00:02:39 +0200 Subject: [PATCH] chore: add README --- README.md | 201 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c7d2e5a --- /dev/null +++ b/README.md @@ -0,0 +1,201 @@ +# GitHub Repository Remover + +A CLI tool for bulk-deleting GitHub repositories with an interactive interface. Built with .NET 9 and Spectre.Console for a clean terminal experience. + +## What it does + +- Interactive repository selection with a clean multi-select interface +- Secure authentication using GitHub Personal Access Tokens +- Batch deletion of multiple repositories +- Multiple confirmation prompts to prevent accidents +- Real-time progress feedback +- Handles GitHub API rate limits gracefully + +## Installation + +### Download and run (recommended) + +No .NET installation required! Just download the executable for your platform: + +1. Head to the [Releases](https://github.com/mtfarkas/GithubRepoRemover/releases) page +2. Download the right file for your system: + - **Windows**: `github-repo-remover-win-x64.exe` + - **macOS**: `github-repo-remover-osx-x64` (Intel) or `github-repo-remover-osx-arm64` (Apple Silicon) + - **Linux**: `github-repo-remover-linux-x64` +3. On macOS/Linux, make it executable: `chmod +x github-repo-remover-*` +4. Run it! + +### Build it yourself + +Need .NET 9.0 SDK installed: + +```bash +git clone https://github.com/mtfarkas/GithubRepoRemover.git +cd GithubRepoRemover +dotnet build -c Release +``` + +## How to use it + +### Basic usage + +```bash +github-repo-remover --token YOUR_GITHUB_TOKEN +``` + +| Option | Short | What it does | Required | +|--------|-------|-------------|----------| +| `--token` | `-t` | Your GitHub Personal Access Token | Yes | + +### Example + +```bash +github-repo-remover --token ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +``` + +Here's what happens when you run it: +1. Authenticates with GitHub using your token +2. Fetches all your repositories +3. Shows you an interactive list to choose from +4. Displays your selected repos for review +5. Asks for confirmation (twice!) +6. Deletes the selected repositories with progress updates + +## Setting up your GitHub token + +You'll need a GitHub Personal Access Token with the right permissions. + +### Creating the token + +1. **Go to GitHub Settings** + - Visit [GitHub.com](https://github.com) + - Click your profile picture → **Settings** + +2. **Navigate to Developer Settings** + - Scroll down and click **Developer settings** + - Click **Personal access tokens** → **Tokens (classic)** + +3. **Create a new token** + - Click **Generate new token** → **Generate new token (classic)** + - Give it a name like "GitHub Repo Remover CLI" + +4. **Set expiration** + - Pick an expiration date that makes sense + - Avoid "No expiration" unless you really need it + +5. **Choose the right permissions** + + **Important:** Your token needs these scopes: + + - ✅ **`repo`** - Full control of private repositories + - ✅ **`delete_repo`** - Delete repositories + + Without both of these, the tool won't work. The `repo` scope lets it read your repository list, and `delete_repo` does what it says on the tin. + +6. **Generate and save the token** + - Click **Generate token** + - **Copy it immediately** - GitHub won't show it again! + - Store it somewhere safe (password manager recommended) + +### Token security tips + +- Never commit tokens to git repositories +- Use a password manager to store them +- Set reasonable expiration dates +- Revoke tokens when you're done with them +- Consider using environment variables for scripts + +### Using environment variables + +If you don't want to type the token every time: + +```bash +# Windows (PowerShell) +$env:GITHUB_TOKEN = "your_token_here" +github-repo-remover --token $env:GITHUB_TOKEN + +# Linux/macOS +export GITHUB_TOKEN="your_token_here" +github-repo-remover --token $GITHUB_TOKEN +``` + +## Safety features + +This tool tries really hard not to let you accidentally delete things: + +- Two separate confirmation prompts before any deletion +- Shows you exactly which repositories will be deleted +- You have to manually select each repository +- Real-time feedback so you know what's happening + +## Error handling + +The tool handles common problems gracefully: +- Invalid or expired tokens get clear error messages +- GitHub rate limiting is handled automatically +- Network problems are reported clearly +- Missing permissions get specific guidance + +## Building from source + +```bash +git clone https://github.com/mtfarkas/GithubRepoRemover.git +cd GithubRepoRemover +dotnet restore +dotnet build -c Release + +# To run it +dotnet run --project src/GithubRepoRemover -- --token YOUR_TOKEN +``` + +## Contributing + +Pull requests welcome! For big changes, please open an issue first so we can discuss it. + +### Development setup + +You'll need .NET 9.0 SDK installed, then: + +1. Clone the repo +2. Run `dotnet restore` +3. Start hacking! + +### Building release executables + +To build the self-contained executables: + +```bash +# Windows +dotnet publish -c Release -r win-x64 --self-contained -p:PublishSingleFile=true + +# macOS Intel +dotnet publish -c Release -r osx-x64 --self-contained -p:PublishSingleFile=true + +# macOS Apple Silicon +dotnet publish -c Release -r osx-arm64 --self-contained -p:PublishSingleFile=true + +# Linux +dotnet publish -c Release -r linux-x64 --self-contained -p:PublishSingleFile=true +``` + +Executables end up in `src/GithubRepoRemover/bin/Release/net9.0/{runtime}/publish/` + +## License + +MIT License + +## Important warning + +**This tool permanently deletes GitHub repositories.** Once they're gone, they're gone (unless you have backups). Make sure you know what you're doing and have backups of anything important. + +I'm not responsible if you accidentally delete something you needed. + +## Getting help + +Run into problems or have ideas? +- [Open an issue](https://github.com/mtfarkas/GithubRepoRemover/issues) for bugs or feature requests +- [Start a discussion](https://github.com/mtfarkas/GithubRepoRemover/discussions) for questions + +--- + +Made with ❤️ by [mtfarkas](https://github.com/mtfarkas) \ No newline at end of file