git-neko

CLI for downloading all repositories from a specified user.

Installation

Via PyPI (Recommended)

pip install git-neko

From Source (Development)

git clone git@github.com:NecRaul/git-neko.git
cd git-neko
# You can skip the next two commands
# for installing it globally
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev,build]

Usage

git-neko acts as a sync tool. If a repo folder doesn't exist, it clones it, if it does, it updates it.

# Download/Sync public repositories with `requests`
git-neko -u <github-username>

# Download/Sync public and private repositories with `requests` (using a token)
git-neko -u <github-username> -t <github-personal-access-token>

# Use 'git clone/pull' instead of 'requests' (preserves history, branches and submodules)
git-neko -u <github-username> -g

# Use 'git' with a token for private repository syncing
git-neko -u <github-username> -t <github-personal-access-token> -g

Environment Variables

You can save your credentials to environment variables to avoid passing them manually in every command.

# Set your credentials as environment variables
git-neko -gu <github-username> -gpat <github-personal-access-token>

# Run using the stored environment variables
git-neko -e

# Run using environment variables with the git engine
git-neko -e -g

Warning

The -gu and -gpat flags for setting environment variables only work on Windows.

It is recommended to set $GITHUB_USERNAME and $GITHUB_PERSONAL_ACCESS_TOKEN variables in your shell profile.

Options

-u, --username      USERNAME    GitHub username to download repositories from
-t, --token         TOKEN       GitHub personal access token (required for private repositories)
-e, --environment   -           Use stored environment variables for username and token
-g, --git           -           Use git engine instead of requests (handles history/branches/submodules)
-gu, --gusername    USERNAME    Save the GitHub username to your environment variables
-gpat, --gpat       TOKEN       Save the GitHub token to your environment variables

Tip

The -e and -g flags are a boolean toggle.

Dependencies

• requests: fetch data from the GitHub API and handle downloads.

How it works

The tool determines the appropriate GitHub API endpoint based on your input: it queries https://api.github.com/users/{username}/repos for public profiles or https://api.github.com/user/repos when a token is provided to include private data.

Once the repo list is retrieved, git-neko automates the synchronization process using one of two engines:

• Requests Engine (Default): Fetches the repo as a compressed snapshot. This is fast but does not include history, branches or submodules.
• Git Engine (via -g or --git flag): Uses your local git installation to perform a full clone or pull This preserves the complete history, branches and submodules.

The Manual Way

Without this tool, you would need to manually parse JSON responses, manage authentication headers, and write logic to differentiate between new clones and existing updates:

# A simplified version of the logic git-neko automates
# It fetches the name and ssh_url, then loops through them
curl -s -H "Authorization: token $GITHUB_PERSONAL_ACCESS_TOKEN" https://api.github.com/user/repos |
    jq -r '.[] | "\(.name) \(.ssh_url)"' | while read -r name ssh_url; do
    if [ ! -d "$name" ]; then
        git clone --recursive "$ssh_url" "$name"
    else
        echo "Pulling '$name'..."
        git -C "$name" pull --recurse-submodules
    fi
done

The git-neko way

• Dynamic API Routing: Automatically identifies the correct GitHub endpoint. It uses /users/{username}/repos for public browsing or the authenticated /user/repos for private access, ensuring you get the full list of repos you have permission to view.
• State-Aware Syncing: Instead of a simple download, it checks your local file system. If a repo already exists, it intelligently switches to an "update" mode (using git pull or overwriting via requests) to keep your local mirror current.
• Hybrid Engine Support:
  • Lightweight Mode: Uses requests to pull repo snapshots quickly without needing git installed or SSH keys configured.
  • Developer Mode (-g): Interfaces directly with your local git binary to handle full history, branch tracking, and submodule recursion.
• Secure Credential Persistence: Rather than requiring you to paste tokens into every command, the -gu and -gpat flags securely interface with your environment variables, allowing for a clean, single-flag execution with -e.
• Subprocess Management: Uses Python's subprocess and os modules to provide a robust bridge between the GitHub API and your local shell, handling directory navigation and command execution automatically.`