{"id":26051469,"url":"https://github.com/ohyaan/gitfleet","last_synced_at":"2026-04-19T12:39:20.258Z","repository":{"id":281105088,"uuid":"940574595","full_name":"ohyaan/gitfleet","owner":"ohyaan","description":"GitFleet is a tool for managing multiple Git repositories through a single configuration file.","archived":false,"fork":false,"pushed_at":"2025-03-07T01:49:30.000Z","size":10,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-07T02:33:17.043Z","etag":null,"topics":["development-tools","git","git-tools","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ohyaan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-28T12:19:47.000Z","updated_at":"2025-03-07T01:49:33.000Z","dependencies_parsed_at":"2025-03-07T02:33:20.550Z","dependency_job_id":"d39c74ff-c291-4c68-9d06-48b871311bd5","html_url":"https://github.com/ohyaan/gitfleet","commit_stats":null,"previous_names":["ohyaan/gitfleet"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohyaan%2Fgitfleet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohyaan%2Fgitfleet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohyaan%2Fgitfleet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohyaan%2Fgitfleet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ohyaan","download_url":"https://codeload.github.com/ohyaan/gitfleet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242501078,"owners_count":20139320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["development-tools","git","git-tools","python"],"created_at":"2025-03-08T04:55:16.683Z","updated_at":"2026-04-19T12:39:20.228Z","avatar_url":"https://github.com/ohyaan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitFleet\n\nGitFleet is a tool for managing multiple Git repositories and GitHub release assets through a single configuration file. It simplifies repository and asset synchronization across teams and environments.\n\n## Key Features\n\n- **Batch Management**: Clone and update multiple repositories simultaneously\n- **GitHub Release Asset Management**: Download and extract assets from GitHub releases\n- **Flexible Configuration**: Support for YAML (recommended) and JSON formats\n- **Flexible Revision Control**: Support for SHA1 hashes, tags, and branches\n- **Git Submodule Integration**: Support for Git submodule\n- **Shallow Clone Support**: Save bandwidth and storage for large repositories\n- **Anchor Functionality**: Lock repository revisions for reproducible environments\n\n## Requirements\n\n- Python 3.12 or later (zero external dependencies for JSON configuration)\n- Git command-line tool\n- PyYAML library (only required when using YAML configuration files)\n\n## Installation\n\n```bash\ncurl -L -o gitfleet https://github.com/ohyaan/gitfleet/blob/main/gitfleet.py\nchmod +x gitfleet\nmv gitfleet /usr/local/bin\n```\n\n### Installing PyYAML (Optional)\n\nIf you want to use YAML configuration files (recommended), install PyYAML:\n\n```bash\n# Using pip\npip install PyYAML\n\n# Using uv\nuv add PyYAML\n```\n\n**Note:** GitFleet will work without PyYAML if you only use JSON configuration files. YAML support is optional and PyYAML is only imported when a YAML file is actually loaded.\n\n## Quick Start Guide\n\n1. Create a `gitfleet.yaml` file in your project's root directory\n2. Define your repositories and/or releases in the configuration\n3. Run `gitfleet` to synchronize all repositories and download assets\n\nGitFleet automatically searches for configuration files in this order:\n1. `gitfleet.yaml`\n2. `gitfleet.yml` \n3. `gitfleet.json`\n\n### Example `gitfleet.yaml`\n\n```yaml\nschemaVersion: v1\nrepositories:\n  - src: https://github.com/xxx/repo1.git\n    dest: external/repo1\n    revision: refs/tags/v1\n  - src: git@github.com:yyy/repo2.git\n    dest: external/repo2\n    revision: refs/heads/main\nreleases:\n  - url: https://github.com/example/repo\n    tag: v1.2.3\n    assets:\n      - name: \"tool-linux-x86_64.tar.gz\"\n        dest: external/tools\n        extract: true\n      - name: \"data-archive.zip\"\n        dest: external/data\n        extract: true\n      - name: \"README.txt\"\n        dest: external/docs\n        extract: false\n```\n\n### Example `gitfleet.json`\n\n```json\n{\n  \"schemaVersion\": \"v1\",\n  \"repositories\": [\n    {\n      \"src\": \"https://github.com/xxx/repo1.git\",\n      \"dest\": \"external/repo1\",\n      \"revision\": \"refs/tags/v1\"\n    },\n    {\n      \"src\": \"git@github.com:yyy/repo2.git\",\n      \"dest\": \"external/repo2\",\n      \"revision\": \"refs/heads/main\"\n    }\n  ],\n  \"releases\": [\n    {\n      \"url\": \"https://github.com/example/repo\",\n      \"tag\": \"v1.2.3\",\n      \"assets\": [\n        { \"name\": \"tool-linux-x86_64.tar.gz\", \"dest\": \"external/tools\", \"extract\": true },\n        { \"name\": \"data-archive.zip\", \"dest\": \"external/data\", \"extract\": true },\n        { \"name\": \"README.txt\", \"dest\": \"external/docs\", \"extract\": false }\n      ]\n    }\n  ]\n}\n```\n\n## Configuration Reference\n\n### Project Structure Example\n```\nmy-project/\n├── gitfleet.yaml    # Primary config file (YAML format - recommended)\n├── src/             # Your project source code\n├── external/        # Directory for managed repositories and assets\n│   ├── repo1/       # First managed repository\n│   ├── repo2/       # Second managed repository\n│   └── assets/      # Downloaded release assets\n└── ...\n```\n\n**Configuration File Priority:**\nGitFleet automatically detects and uses the first available configuration file:\n1. `gitfleet.yaml`\n2. `gitfleet.yml` \n3. `gitfleet.json`\n\n### Repository Configuration Options\n\nEach repository entry supports the following properties:\n\n| Property | Description | Required | Default |\n|----------|-------------|----------|---------|\n| `src` | Repository URL (HTTPS or SSH) | Yes | - |\n| `dest` | Local destination path | Yes | - |\n| `revision` | Git revision specification | Yes | - |\n| `shallow-clone` | Enable shallow clone | No | `false` |\n| `clone-submodule` | Clone submodule | No | `false` |\n| `clone-subfleet` | Process nested fleet file | No | `false` |\n| `copy` | Selective file/directory copy list (see below) | No | - |\n\n#### Selective File/Directory Copy (`copy.repoPath`)\n\nYou can optionally specify a `copy` section for each repository to copy only specific files or directories from the cloned repository to arbitrary destinations. The full repository is always cloned to the `dest` directory (which is retained as a backup), but you can additionally copy selected files or directories elsewhere.\n\nExample:\n\n```yaml\nrepositories:\n  - src: https://github.com/example/repo.git\n    dest: external/repo1234\n    revision: refs/heads/main\n    copy:\n      - repoPath: file1.txt           # Relative path inside the repository\n        dest: src/file1.txt           # Destination path (relative to fleet config or absolute)\n      - repoPath: src/dir2/           # Directory also supported\n        dest: src/b/selected/dir2/\n```\n\n- `repoPath`: Path to the file or directory inside the repository (relative to the repository root).\n- `dest`: Destination path to copy to (relative to the fleet configuration file or absolute).\n\nIf `copy` is omitted, the repository is only cloned to `dest` as before.\n\nBehavior:\n- The repository is always cloned to the specified `dest` directory.\n- If `copy` is specified, only the listed files/directories are copied from the repository to the specified destinations.\n- The `dest` directory is always retained as a backup of the full repository, regardless of whether `copy` is used.\n\nEach `copy` entry supports:\n\n| Property   | Description                                         | Required | Default |\n|------------|-----------------------------------------------------|----------|---------|\n| `repoPath` | Path to file or directory in the repository         | Yes      | -       |\n| `dest`     | Destination path to copy to (relative/absolute)     | Yes      | -       |\n\n---\n\n\n#### Revision Formats\n\nGitFleet supports three revision formats:\n- **SHA1**: `\"revision\": \"a1b2c3d4e5f6\"` (exact commit)\n- **Tags**: `\"revision\": \"refs/tags/v1\"` (specific version)\n- **Branches**: `\"revision\": \"refs/heads/main\"` (latest on branch)\n\n### Release Configuration Options\n\nAdd a top-level `releases` property to your configuration file. Each release entry supports the following properties:\n\n| Property      | Description                                              | Required | Default |\n|---------------|----------------------------------------------------------|----------|---------|\n| `url`         | GitHub repository URL (HTTPS)                            | Yes      | -       |\n| `tag`         | Release tag (e.g., `v1.2.3`)                            | Yes      | -       |\n| `assets`      | List of asset file objects to download                   | Yes      | -       |\n\nEach file object in `assets` supports:\n\n| Property   | Description                                 | Required | Default |\n|------------|---------------------------------------------|----------|---------|\n| `name`     | Asset file name in the release              | Yes      | -       |\n| `dest`     | Local destination path (relative/absolute)  | Yes      | -       |\n| `extract`  | Extract archive after download              | No       | `true`  |\n\n#### Example: Downloading and Extracting Release Assets\n\n```yaml\nschemaVersion: v1\nreleases:\n  - url: https://github.com/example/repo\n    tag: v1.2.3\n    assets:\n      - name: \"tool-linux-x86_64.tar.gz\"\n        dest: external/tools\n        extract: true\n      - name: \"data-archive.zip\"\n        dest: external/data\n        extract: true\n      - name: \"README.txt\"\n        dest: external/docs\n        extract: false\n```\n\n- You can flexibly specify the destination and whether to extract for each file.\n- If `extract` is omitted, it defaults to `true`.\n\n### Notes\n- Release assets are always fetched by tag.\n- Extraction is supported for the listed archive formats only.\n- The `releases` section is optional and backward compatible.\n- All features work with both YAML and JSON configuration files.\n\n## Advanced Usage\n\n### Anchoring Repositories\n\nLock all your repositories to specific commit SHAs for reproducibility:\n\n```bash\ngitfleet --anchor           # Update config file in place\ngitfleet --anchor fleet-anchored.json  # Save to a new file\n```\n\n#### Use Cases for Anchoring:\n- **Reproducible Builds**: Ensure consistent environments\n- **Release Management**: Snapshot dependencies for releases\n- **Debugging**: Record exact repository states for troubleshooting\n\n### Working with Submodule\n\nEnable submodule processing with the `clone-submodule` option:\n\n```yaml\nschemaVersion: v1\nrepositories:\n  - src: https://github.com/xxx/repo1.git\n    dest: external/repo1\n    revision: refs/tags/v1\n    clone-submodule: true\n```\n\n### Working with SubFleet\n\nSupport hierarchical repository management with `clone-subfleet`:\n\n```yaml\nschemaVersion: v1\nrepositories:\n  - src: https://github.com/username/sub-project.git\n    dest: external/sub-project\n    revision: refs/heads/main\n    clone-subfleet: true\n```\n\nGitFleet will process the `gitfleet.yaml` (or `gitfleet.json`) found in the sub repository.\n\n## Command Line Options\n\n```bash\ngitfleet [OPTIONS]\n```\n\n### Options\n\n| Option | Description |\n|--------|-------------|\n| `-h, --help` | Show help message and exit |\n| `--version` | Show program version |\n| `--dry-run` | Show what would be done without executing |\n| `--force-shallow-clone` | Force shallow clone for all repositories |\n| `--anchor [FILE]` | Anchor repositories to current SHA1 commits |\n| `--parallel N` | Maximum number of concurrent workers (default: 4) |\n| `--verbose` | Enable verbose output with detailed logging |\n\n### Examples\n\n```bash\ngitfleet\n# Process default configuration file (searches for gitfleet.yaml, gitfleet.yml, then gitfleet.json)\n\ngitfleet --dry-run\n# Dry run to see what would happen\n\ngitfleet --force-shallow-clone\n# Force shallow clones for all repositories\n\ngitfleet --anchor anchored-fleet.yaml\n# Anchor all repositories and save to new file\n\ngitfleet --parallel 8\n# Use more workers for faster processing\n\ngitfleet --verbose\n# Enable verbose logging\n```\n\n## Complete Configuration Example\n\nHere's a comprehensive example showcasing all available features:\n\n```yaml\nschemaVersion: v1\nrepositories:\n  # Basic repository\n  - src: https://github.com/example/basic-repo.git\n    dest: external/basic-repo\n    revision: refs/heads/main\n\n  # Repository with specific tag\n  - src: https://github.com/example/versioned-repo.git\n    dest: external/versioned-repo\n    revision: refs/tags/v2.1.0\n\n  # Repository with specific commit SHA\n  - src: https://github.com/example/locked-repo.git\n    dest: external/locked-repo\n    revision: a1b2c3d4e5f67890abcdef1234567890abcdef12\n\n  # Repository with submodules\n  - src: git@github.com:private/repo-with-submodules.git\n    dest: external/repo-with-submodules\n    revision: refs/heads/develop\n    clone-submodule: true\n\n  # Repository with nested fleet\n  - src: https://github.com/example/meta-project.git\n    dest: external/meta-project\n    revision: refs/heads/main\n    clone-subfleet: true\n\n  # Large repository with shallow clone\n  - src: https://github.com/example/large-repo.git\n    dest: external/large-repo\n    revision: refs/heads/main\n    shallow-clone: true\n\nreleases:\n  - url: https://github.com/example/repo\n    tag: v1.2.3\n    assets:\n      - name: \"tool-linux-x86_64.tar.gz\"\n        dest: external/tools\n        extract: true\n      - name: \"data-archive.zip\"\n        dest: external/data\n        extract: true\n      - name: \"README.txt\"\n        dest: external/docs\n        extract: false\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Q: GitFleet can't find my configuration file**\n```\nError: Cannot find fleet configuration file in /path/to/directory. Looking for: gitfleet.yaml, gitfleet.yml, gitfleet.json\n```\nA: Ensure at least one of the supported configuration files exists in your current directory. GitFleet searches for files in this priority order: `gitfleet.yaml` → `gitfleet.yml` → `gitfleet.json`\n\n**Q: Repository clone fails with permission errors**\n```\nError: Failed to clone repository\n```\nA: Check your SSH keys or access credentials. For private repositories, ensure proper authentication:\n```bash\n# Test SSH access\nssh -T git@github.com\n\n# Or use HTTPS with credentials\ngit config --global credential.helper store\n```\n\n**Q: Submodule processing fails**\nA: Ensure the repository has proper `.gitmodules` file and submodule URLs are accessible.\n\n**Q: Performance is slow with many repositories**\nA: Increase the number of workers:\n```bash\ngitfleet --parallel 8\n```\n\n### Best Practices\n\n1. **Use shallow clones for large repositories** to save bandwidth and storage\n2. **Pin specific versions** using tags or SHA1 for production environments\n3. **Test with --dry-run** before applying changes to important projects\n4. **Use anchoring** to create reproducible snapshots of your dependencies\n5. **Organize repositories and assets** in logical directory structures under `external/`\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohyaan%2Fgitfleet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fohyaan%2Fgitfleet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohyaan%2Fgitfleet/lists"}