FoxGit

FoxGit is a self-hosted Git cockpit for LANX.

Forgejo stays the Git engine. FoxGit becomes the daily workspace for browsing, editing, committing, and syncing projects.

Browse. Understand. Edit. Commit. Sync.

What FoxGit does

FoxGit provides a clean web interface for working with local Git repositories connected to Forgejo.

Current v1.1 features include:

• first-run setup for creating the first FoxGit admin
• optional Forgejo setup modes: skip, link existing user, or create new user
• CLI-only recovery through scripts/foxgit-recovery.py
• read-only user desktop
• repository landing pages
• README preview
• Forgejo metadata bridge
• Forgejo create, import, attach/link, and first-push support
• recent Git activity panel
• repository overview, stats, analytics, and lifecycle cards
• file browser
• file viewer and editor
• Git status overview
• file diff viewer
• commit history
• staged-only commit flow
• pull, push, fetch, and sync tools
• branch management
• cleanup and ignore assistant
• GUI backup from the admin cockpit
• screenshot manual with 32 guided UI images
• admin cockpit separated from normal user mode

Manual

The screenshot manual gives a guided tour through the FoxGit v1.1 interface, while the handbook explains the workflows, safety model, recovery notes, and operating practices:

• FoxGit Screenshot Manual
• FoxGit Handbook

Design goal

FoxGit is not meant to replace Forgejo.

Forgejo remains the Git server, authentication provider, repository host, and long-term source of truth.

FoxGit is the dashboard layer.

The goal is simple:

FoxGit = daily workspace and project dashboard
Forgejo = Git engine and repository backend

User mode

User mode is read-only and safe.

It is meant for browsing projects, reading documentation, opening files, and understanding repository activity without exposing destructive Git actions.

User mode includes:

• project landing page
• README preview
• project facts
• Forgejo metadata
• recent activity
• file browsing
• direct Forgejo link
• clone URL copy actions

Admin cockpit

Admin mode unlocks the tools needed to work on repositories directly.

Admin tools include:

• edit files
• create files and folders
• rename and delete paths
• Git status
• diffs
• commits
• branches
• pull, push, fetch, and sync
• repository cleanup tools
• analytics and stats views

Architecture

FoxGit is built as a simple FastAPI backend with a vanilla JavaScript frontend.

The current stack is intentionally low-complexity:

• FastAPI
• Uvicorn
• vanilla HTML/CSS/JavaScript
• SQLite runtime state
• local Git repositories
• Forgejo OAuth
• Forgejo API metadata bridge
• Docker runtime

Security model

FoxGit separates normal browsing from admin operations.

Read-only repository browsing is available to user mode, while Git write actions and cockpit tools are locked behind admin authentication and role mapping.

Fresh installs use first-run setup to create the first local admin.

After setup completes, web setup closes. Recovery is CLI-only.

Preferred recovery command inside Docker runtime:

docker exec -it foxgit python3 /app/scripts/foxgit-recovery.py status

Local fallback admin authentication uses a password hash, not cleartext storage.

Runtime secrets, Forgejo tokens, OAuth secrets, and Git credentials must not be committed.

Status

FoxGit is currently at v1.1 stable release stage.

The core dashboard direction is established:

• user desktop
• project landing page
• first-run setup
• CLI recovery
• Forgejo metadata and lifecycle bridge
• repo activity
• admin cockpit
• sync-safety and first-push flows

Next likely work areas:

• release/changelog panel
• issue/activity bridge
• backup/export polish
• future v1.2 planning

Credits

Built with ❤️ for Lanx by NodeFox 🦊

Maintained by Eddie Nielsen

Learn. Adopt. Survive. Share.