installation

Installation & Setup

The setup path

flowchart TD
    I[INSTALL] --> V[VERIFY ENVIRONMENT]
    V --> A[AUTHENTICATE GITHUB]
    A --> R[REGISTER URGITHUB]
    R --> B[CHOOSE REPOSITORY BASE]
    B --> D[DISCOVER REPOSITORIES]
    D --> S[SCAN]
    S --> L[VALIDATE]
    L --> SY[SYNC / COMMIT / PUSH]
    SY --> VF[VERIFY]
    VF --> G[GENERATE REPORT]

Loading

Installation ≠ registration ≠ scanning ≠ synchronization — a newly installed tool never makes uncontrolled repository changes.

1. Install the tools

Tool	Windows	Linux / macOS
Python 3.10+	winget install Python.Python.3.12	Distro package / brew install python
Git	winget install Git.Git	apt install git / brew install git
GitHub CLI	winget install GitHub.cli	apt install gh / brew install gh

Note: Restart your terminal after installing Git / gh so PATH updates.

2. Verify the environment

python --version
git --version
gh --version
gh auth status
git config --global user.name
git config --global user.email

A healthy environment looks like:

Python       ✓
Git          ✓
Git identity ✓
GitHub CLI   ✓
GitHub auth  ✓

If one of these checks fails, fix it before continuing.

If the git identity is empty, set it before committing works:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Git identity is the author identity for commits — it is not your GitHub authentication credential. URGithub authenticates through the GitHub CLI session and expects the repo scope on the token (gh auth status). Never place tokens into URGithub config files manually.

3. Clone the repository

gh repo clone learnerforge/push-to-github
cd push-to-github
python urgithub.py --version   # or python3 urgithub.py --version

4. Run the setup wizard

# Linux / macOS
python3 urgithub.py --setup

# Windows (PowerShell / CMD)
python urgithub.py --setup

The wizard checks, in order:

1. Python
2. Git
3. GitHub CLI
4. GitHub authentication
5. Repository permissions
6. The selected workspace
7. Creates the URGithub directory structure
8. Registers the installation
9. Creates the initial configuration
10. Prepares URGithub for its first run

Everything in one command (Windows)

python urgithub.py --setup-all

Registers (if needed), installs the scheduled tasks (UAC prompt for the shutdown task), runs the first sync and shows status.

5. First run

Recommended sequence for a new installation:

python urgithub.py --scan      # discover repos
python urgithub.py --repos     # list what was found
python urgithub.py --verify    # health check
python urgithub.py --sync      # synchronize

Open the report with python urgithub.py --report or find it at <base>\urgithub\.urgithub\reports\report.html.

The full recommended first-run procedure (12 steps):

1.  Verify Python            python --version
2.  Verify Git               git --version
3.  Verify Git identity      git config --global user.name / user.email
4.  Verify GitHub CLI        gh --version
5.  Verify GitHub auth       gh auth status
6.  Register                 python urgithub.py --setup
7.  Scan                     python urgithub.py --scan
8.  Inspect repositories     python urgithub.py --repos
9.  Verify                   python urgithub.py --verify
10. Synchronize              python urgithub.py --sync
11. Inspect the report       report.html
12. Configure automation     --schedule install (Windows) or cron/systemd/launchd

6. Minimal setup

gh repo clone learnerforge/push-to-github
cd push-to-github
python3 urgithub.py --setup
python3 urgithub.py

That is enough to be registered, synchronized and reporting.

Useful commands

Command	What it does
--setup	One-time registration wizard
--setup-all	Register + schedule + first run + status (Windows)
--startup	Run the startup trigger — full pipeline
--shutdown	Shutdown quick-push (30 s hard timeout, never opens report)
--scan / --sync	Run discovery / synchronization now
--repos / --verify	List repositories / verify the environment
--run manual	Run the manual trigger
--watch	Start the file watcher
--tray / (no args)	Open the Control Center GUI
--schedule install	Install scheduling (Windows Task Scheduler)
--forget NAME / --prune	Registry cleanup
--config	Show / read / set configuration
--version / --help	Version / help

Run python urgithub.py --help for the full command list supported by your installed version.

Next: Configuration — every config key and how to change it.