Skip to content

README.md

Latest commit

 

History

History
155 lines (119 loc) · 6.08 KB

README.md

File metadata and controls

155 lines (119 loc) · 6.08 KB
Raw

🇩🇪 Zur deutschen Dokumentation wechseln | 🇬🇧 Switch to English Documentation

🚀 UpGit — GitHub TUI Uploader & Repository Manager

GitHub Author Platform Python TUI License

UpGit TUI Preview

UpGit is an autonomous, professional Terminal User Interface (TUI) utility built to streamline publishing local directory projects directly to GitHub.

It features a single-login architecture: Once you provide your GitHub Personal Access Token (PAT), UpGit validates and links with your GitHub account (@Graba92) and securely stores credentials under ~/.config/upgit/auth.json with hardened 0600 permissions.

✨ Features

  • 🔑 Single-Login & Account Synchronization:
    • One-time token input verified instantly against the GitHub REST API v3.
    • Auto-Import: Seamlessly detects and imports existing tokens from the official GitHub CLI (gh auth token) with 1 click.
    • Live Profile Stats: Real-time display of user profile, public & private repository counters, and remaining API rate limits.
    • Security First: Credentials are saved strictly with 0600 permissions and are never committed or stored in plaintext inside .git/config.
  • 📁 Workspace Project Scanner:
    • Audits directories for GitHub release readiness:
      • Validates presence of README.md, LICENSE, and .gitignore.
      • Detects git repository initialization status (.git), active branch, and uncommitted file count.
    • Autonomous metadata extraction: Pulls project descriptions directly from existing local README files.
  • 🚀 1-Click GitHub Repository Upload:
    • Remote Provisioning: Automatically creates the repository on GitHub via REST API if it doesn't already exist (Public or Private).
    • Local Git Orchestration: Handles git init -b main, git user setup, staging (git add .), initial commit, and secure remote push.
    • Live Log Modal: Real-time streaming console showing step-by-step progress and output.
    • Generates clickable GitHub URLs upon completion.

🏛️ Architecture & Project Structure

upgit/
├── app.py                      # Universal CLI & TUI entry point
├── upgit_app.py                # Textual Master TUI Application
├── run.sh                      # Universal launcher
├── setup.sh                    # Automated setup & installer (pacman / venv)
├── requirements.txt            # Python dependencies (textual, rich)
├── README.md                   # English documentation (this file)
├── README_DE.md                # German documentation
├── LICENSE                     # MIT License (Matthias Haase / Graba92)
├── .gitignore                  # Git ignore rules
│
├── core/                       # Low-level system & business logic
│   ├── auth.py                 # Token storage, 0600 hardening & gh CLI import
│   ├── github_api.py           # Native REST API engine (User, Check, Create Repo)
│   ├── git_manager.py          # Local Git engine (Init, Commit, Remote & Push)
│   └── scanner.py              # Project scanner & README parser
│
└── ui/                         # Modern Textual interface layer
    ├── theme.py                # Nordic Dark TCSS stylesheet
    └── screens/                # Modals and ergonomic views
        ├── auth_screen.py      # Token input & authentication modal
        ├── upload_modal.py     # Upload configuration (Name, Visibility, Commit)
        └── log_modal.py        # Real-time execution log modal

🚀 Installation & Setup

1. Automated Quick Setup (Recommended)

git clone https://github.com/Graba92/upgit.git
cd upgit
chmod +x setup.sh run.sh
./setup.sh

2. Native Pacman (Arch Linux / CachyOS)

sudo pacman -S --needed python-textual python-rich git

3. Manual Virtual Environment Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

🖥️ Usage

1. Interactive TUI

./run.sh
# or launch with explicit language
python3 app.py --lang en
python3 app.py --lang de

2. Headless CLI Commands

# Query active GitHub login and token status (in English or German):
python3 app.py --status --lang en

# List and audit projects in a directory:
python3 app.py --list ..

# Remove saved token (Logout):
python3 app.py --logout

# Print version:
python3 app.py --version

⌨️ Keybindings

Key Action
l Toggle language between English and Deutsch
u / Enter Upload highlighted project to GitHub
r Refresh project workspace scanner
s Synchronize GitHub profile & rate limit
t Open Token & Authentication Manager
q Cleanly exit UpGit

🛡️ Creating a GitHub Personal Access Token (PAT)

If you need a new token:

  1. Navigate to: github.com/settings/tokens.
  2. Click Generate new token (classic).
  3. Select expiration (e.g. 90 days or No expiration).
  4. Select the necessary scopes:
    • [x] repo (Full control of private and public repositories).
    • (Optional) [x] workflow (for GitHub Actions).
  5. Click Generate token, copy the token string (ghp_...), and paste it into UpGit.

📄 License

This project is licensed under the MIT License — Copyright (c) 2026 Matthias Haase (Graba92).