Refactor git-clone CLI compatibility

Replace the previous flag contract with a git-oriented parser based on pflag and keep the compatibility logic inside the main package.

Align common git clone behavior around exit codes, destination handling, branch/tag resolution, progress output, and explicit unsupported-option failures.

Document the supported surface, keep non-Git extensions long-only, remove the legacy tags/<name> branch form, and add integration coverage for the new contract.

Author: n0madic

README.md

@@ -1,68 +1,105 @@
-# git-clone 
+# git-clone
 
-Summary
--------
-Git clone standalone. Git repository downloader.
+`git-clone` is a standalone repository downloader built on top of `go-git`. It is intended to be a practical drop-in replacement for common `git clone` workflows without requiring a full Git installation.
 
-Can fetch repositories without installing Git environment!
+Where `go-git` supports the underlying behavior directly, the utility follows Git-compatible argument names, exit codes, destination checks, and branch or tag checkout semantics. Features that cannot be reproduced faithfully are either accepted as compatibility no-ops or rejected early with a git-like error.
 
-Help
-----
-```
-Usage:
-  git-clone [OPTIONS] repository [directory]
-
-Application Options:
-  -i, --identity=<file>            Selects a file from which the identity (private key) for public key
-                                   ssh authentication is read. Or use the environment variable
-                                   [$GIT_CLONE_KEY]
-  -r, --recursive                  After the clone is created, initialize all submodules within, using
-                                   their default settings.
-  -p, --pull                       Incorporates changes from a remote repository into the current branch
-                                   (if already cloned).
-  -o, --origin=<name>              Instead of using the remote name origin to keep track of the upstream
-                                   repository, use <name>. (default: origin)
-  -b, --branch=<name>              Instead of pointing the newly created HEAD to the branch pointed to by
-                                   the cloned repository’s HEAD, point to <name> branch instead.
-      --single-branch              Clone only the history leading to the tip of a single branch, either
-                                   specified by the --branch option or the primary branch remote’s HEAD
-                                   points at.
-  -d, --depth=<depth>              Create a shallow clone with a history truncated to the specified
-                                   number of commits.
-  -t, --tags=[all|no|following]    Tag mode (default: all)
-  -l, --last                       Print the latest commit.
-
-Help Options:
-  -h, --help                       Show this help message
-
-Arguments:
-  repository:                      The repository to clone from.
-  directory:                       The name of a new directory to clone into.
-```
+## Compatibility
+
+### Supported
+
+- `repo [dir]`
+- `-v/--verbose`
+- `-q/--quiet`
+- `--progress`, `--no-progress`
+- `-n/--no-checkout`, `--checkout`
+- `--bare`, `--no-bare`
+- `--mirror`, `--no-mirror`
+- `-s/--shared`, `--no-shared`
+- `--recursive`, `--no-recursive`
+- `--recurse-submodules`, `--no-recurse-submodules`
+- `-o/--origin`
+- `-b/--branch`
+- `--single-branch`, `--no-single-branch`
+- `--depth`
+- `--tags`, `--no-tags`
+- `--shallow-submodules`, `--no-shallow-submodules`
+
+### Supported As Compatibility No-Ops
+
+These flags are accepted to preserve CLI compatibility, but this build does not emulate Git's transport/storage optimization behind them:
 
-Usage
------
+- `-l/--local`, `--no-local`
+- `--hardlinks`, `--no-hardlinks`
 
-$ ``git-clone https://github.com/n0madic/git-clone.git``
+### Partial Support
 
-Clone to another dir:  
-$ ``git-clone https://github.com/n0madic/git-clone.git foo``  
-$ ``git-clone https://github.com/n0madic/git-clone.git ~/bar``
+- `-c/--config key=value`
+  - applied to the local repository config after clone/pull
+  - does not influence transport-time behavior the way vanilla Git can
+- `--recursive[=<pathspec>]` / `--recurse-submodules[=<pathspec>]`
+  - supported without a pathspec
+  - pathspec form is rejected early as unsupported
+- `-b/--branch`
+  - supports both branches and tags
+  - if a branch and tag share the same name, branch wins like vanilla Git
 
-Cloning specific branch:  
-$ ``git-clone -b develop https://github.com/n0madic/git-clone.git``  
-Note: if the repository already cloned, it will simply switch the branch, and local changes will be discarded.
+### Recognized But Unsupported
 
-Download a specific tag:  
-$ ``git-clone -b tags/v0.1.0 https://github.com/n0madic/git-clone.git``  
+These options are parsed and fail early with exit code `129` and a git-like error:
 
-Pull if repository already cloned (if not then just clone):  
-$ ``git-clone --pull https://github.com/n0madic/git-clone.git``
+- `--reject-shallow`, `--no-reject-shallow`
+- `-j/--jobs`, `--no-jobs`
+- `--template`
+- `--reference`
+- `--reference-if-able`
+- `--dissociate`
+- `--revision`
+- `-u/--upload-pack`
+- `--shallow-since`
+- `--shallow-exclude`
+- `--separate-git-dir`
+- `--ref-format`
+- `--server-option`
+- `-4/--ipv4`
+- `-6/--ipv6`
+- `--filter`
+- `--also-filter-submodules`
+- `--remote-submodules`
+- `--sparse`, `--no-sparse`
+- `--bundle-uri`
 
-Use custom private key from file:  
-$ ``git-clone --identity ~/.ssh/id_rsa.foo git@github.com:n0madic/git-clone.git``
+## Extensions
 
-Use custom private key from environment:  
-$ ``export GIT_CLONE_KEY=$(cat ~/.ssh/id_rsa.bar)``  
-$ ``git-clone git@github.com:n0madic/git-clone.git``  
-Note: --identity flag has a higher priority over the environment.
+These are intentionally outside vanilla `git clone`, but remain available as long-only flags so they do not collide with Git's standard short options:
+
+- `--pull`
+  - if destination already exists as a repository, pull instead of failing
+  - plain clone behavior remains Git-compatible unless `--pull` is explicitly set
+- `--last`
+  - prints the latest checked out commit after clone/pull
+- `--identity <file>`
+  - uses the given SSH private key file or PEM contents
+  - also respects `GIT_CLONE_KEY`
+
+## Behavioral Notes
+
+- Exit codes follow Git-style conventions:
+  - `0` success
+  - `128` fatal runtime/semantic failure
+  - `129` usage, help, unknown option, unsupported option
+- Progress is written to `stderr`, not `stdout`.
+- Progress is shown automatically only when `stderr` is a terminal, unless `--progress` forces it or `--quiet` / `--no-progress` disables it.
+- Existing non-empty destinations now fail like vanilla `git clone`.
+- Existing repositories are only mutated when `--pull` is explicitly used.
+
+## Examples
+
+```bash
+git-clone https://github.com/n0madic/git-clone.git
+git-clone -b main https://github.com/n0madic/git-clone.git dst
+git-clone --no-tags --depth 1 https://github.com/n0madic/git-clone.git
+git-clone --recursive https://github.com/n0madic/git-clone.git
+git-clone --pull https://github.com/n0madic/git-clone.git
+git-clone --identity ~/.ssh/id_ed25519 git@github.com:n0madic/git-clone.git
+```