Metadata-Version: 2.4
Name: git-clone-group
Version: 1.2.6
Summary: Clone or update all projects from a GitLab group and its subgroups
Home-page: https://github.com/bpzhang/git_clone_group
Author: bp zhang
Author-email: zbp1024@gmail.com
License: Proprietary
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.10
Requires-Dist: tqdm>=4.66
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


# Git Clone Group (gcg)

A command-line tool to clone or update all projects from a GitLab group and its subgroups.

## Features

- Clone/update all repositories in a GitLab group and its subgroups
- Support both group ID and group name/path
- Specify branch to clone/pull
- Parallel processing with progress bars
- Smart retry mechanism
- Empty repository detection
- Detailed statistics

## Installation

You can install git-clone-group using pip:

```bash
pip install git-clone-group
```

### Working on the project with `pyenv` and `uv`

The repository is configured to use [pyenv](https://github.com/pyenv/pyenv) for the
interpreter version and [uv](https://docs.astral.sh/uv/) for dependency management.

```bash
# Install and activate the pinned interpreter
pyenv install 3.14.0 --skip-existing
pyenv local 3.14.0

# Sync dependencies into .venv/ using uv
uv sync

# Run the CLI from the managed environment
uv run gcg -h
```

When new dependencies are added, update the lock file with

```bash
uv lock
```

## Usage

Basic usage:

```bash
# By group ID
gcg -g GITLAB_ADDR -t TOKEN -i GROUP_ID [-d DEST_DIR] [-b BRANCH] [-y]

# By group name/path
gcg -g GITLAB_ADDR -t TOKEN -n GROUP_NAME [-d DEST_DIR] [-b BRANCH] [-y]

# No group specified: list all accessible groups, summarize repo counts, and prompt to proceed
gcg -g GITLAB_ADDR -t TOKEN [-d DEST_DIR] [-b BRANCH] [-y]
```

Show help:

```bash
gcg -h
```

Examples:

```bash
# Clone all projects from group ID 123 to current directory
gcg -g gitlab.com -t glpat-xxxxxxxxxxxx -i 123

# Clone/update all projects from group named 'my-team'
gcg -g gitlab.com -t glpat-xxxxxxxxxxxx -n my-team

# Clone from nested group using full path
gcg -g gitlab.com -t glpat-xxxxxxxxxxxx -n organization/my-team

# Clone to a specific directory
gcg -g gitlab.com -t glpat-xxxxxxxxxxxx -n my-team -d /path/to/repos

# Clone specific branch from private GitLab instance
gcg -g git.company.com -t glpat-xxxxxxxxxxxx -n my-team -d ./projects -b develop

# Clone default branches using group ID
gcg -g gitlab.com -t glpat-xxxxxxxxxxxx -i 123 -d ./repos

# Pull ALL accessible groups (will list a summary and ask for confirmation)
gcg -g gitlab.com -t glpat-xxxxxxxxxxxx

# Non-interactive: skip confirmation when running all groups
gcg -g gitlab.com -t glpat-xxxxxxxxxxxx -y
```

## Getting a GitLab Access Token

1. Log in to your GitLab instance
2. Go to Settings > Access Tokens
3. Create a new personal access token with `api` scope
4. Copy the token and use it with the `--token` argument

## Getting a Group ID or Name

### Group ID

You can find the group ID in GitLab:

1. Go to your group's page
2. The group ID is shown in the group information panel
3. Or look at the URL: `https://gitlab.com/groups/your-group-name` - the group ID will be visible in the group details

### Group Name/Path

You can use the group name or full path:

- Simple group name: `my-team`
- Full group path: `organization/my-team`
- If multiple groups match the search, you'll be prompted to choose

## Notes

- The tool will automatically handle nested subgroups
- For existing repositories, it will perform a git pull
- Progress bars show real-time cloning/pulling status
- Both HTTP and SSH URLs are supported (SSH recommended)
- When using group names, if multiple matches are found, you'll be prompted to select the correct one
- If no group is specified, the tool will list all groups accessible by your token with the counts of groups and projects, then prompt you to proceed. Use `-y/--yes` to skip confirmation in non-interactive environments.
