Metadata-Version: 2.4
Name: git_neko
Version: 1.26
Summary: CLI for downloading all repositories from a specified user.
Home-page: https://github.com/NecRaul/git-neko
Author: NecRaul
Author-email: NecRaul <necraul@kuroneko.dev>
License-Expression: LGPL-2.1-only
Project-URL: Homepage, https://github.com/NecRaul/git-neko
Project-URL: Documentation, https://github.com/NecRaul/git-neko#readme
Project-URL: Repository, https://github.com/NecRaul/git-neko
Project-URL: Issues, https://github.com/NecRaul/git-neko/issues
Keywords: python,repository downloader,downloader,repository,git-neko,kuroneko
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: flake8; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: build
Requires-Dist: build; extra == "build"
Requires-Dist: twine; extra == "build"
Dynamic: author
Dynamic: home-page
Dynamic: license-file

# git-neko

CLI for downloading all repositories from a specified user.

## Installation

### Via PyPI (Recommended)

```sh
pip install git-neko
```

### From Source (Development)

```sh
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.

```sh
# 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.

```sh
# 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

```sh
-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](https://github.com/psf/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:

```sh
# 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.`
