DOCSEARCHbyAlgolia
Submit Docs

multi-gitter

repository·master·Indexed 22 days ago

https://github.com/lindell/multi-gitter

A tool for performing programmatic changes across multiple repositories simultaneously. It executes scripts or programs in the context of each repository and automatically creates pull requests for detected changes. It supports multiple platforms including GitHub, GitLab, Gitea, Bitbucket Server, Bitbucket Cloud (Beta), and Gerrit. Key commands include `run` for automating changes, `merge` for merging PRs, `status` for checking PR progress, `close` for closing PRs, and `print` for executing read-only scripts and auditing output.

Tokens
12.8K
Snippets
19
Records
42
Agent score
73%

What's inside multi-gitter

  1. Use the `print` command to run scripts and view output

    master

    The print command clones multiple repositories and executes a specified script in each. Unlike run, it does not create pull requests; instead, it prints the output (stdout and stderr) of each script run. This is useful for auditing or running read-only scripts across many repos.

    When the script is running, multi-gitter sets the following environment variables:

    • REPOSITORY: The name of the repository currently being processed.

    You can configure where the output and error logs are written using --output and --error-output flags.

    multi-gitter print [script path] [flags]

  2. Configure multi-gitter using config files

    master

    Multi-gitter supports configuration via command line flags, configuration files, or a combination of both.

    To use a specific configuration file, use the --config flag:

    multi-gitter --config=./path/to/config.yaml [other-options]

    Configuration Priority:

    1. Command line flags (highest priority)
    2. Defined configuration files (later files in a list override earlier ones)
    3. The static config file located at ~/.multi-gitter/config (lowest priority)

    You can specify the --config flag multiple times to layer configurations.

  4. Run a script or program across multiple repositories

    master

    The multi-gitter run command executes a script or program in the context of multiple repositories. If changes are detected, multi-gitter creates a pull request that can be merged manually or automatically once CI passes.

    Running an executable file

    Ensure the script has execution permissions (chmod +x) before running.

    multi-gitter run ./my-script.sh -O my-org -m "Commit message" -B branch-name

    Running via an interpreter

    When using an interpreter (Python, Node, Go, etc.), use absolute paths for the script to ensure it is found correctly when executed within the context of each target repository. Using the $PWD variable is a common way to achieve this.

    # Python
multi-gitter run "python $PWD/run.py" -O my-org -m "Commit message" -B branch-name

# Node.js
multi-gitter run "node $PWD/script.js" -R repo1 -R repo2 -m "Commit message" -B branch-name

# Go
multi-gitter run "go run $PWD/main.go" -U my-user -m "Commit message" -B branch-name

  5. Add your own example script

    master

    To contribute a new example to multi-gitter, add your script to the corresponding language folder (or the general folder).

    Requirement: You must include a Title: xxx comment at the top of your script. This comment is used by automated tools to parse and display your example. Use a single-line comment format appropriate for the language you are using.

    # Title: My bash script that does X
    // Title: My js script that does X

  6. Use the `run` command to automate changes across repositories

    master

    The run command clones multiple repositories, executes a specified script within the context of each repository, and automatically creates a pull request if the script succeeds (exit code 0) and results in file changes.

    When your script is running, multi-gitter sets the following environment variables:

    • REPOSITORY: The name of the repository currently being processed.
    • DRY_RUN: Set to true if the --dry-run flag is used; otherwise, it is absent.

    Use --dry-run to test your script and target selection without actually pushing changes or creating pull requests.

    multi-gitter run [script path] [flags]

  7. Use Bitbucket Cloud with multi-gitter

    master

    Bitbucket Cloud support is currently in Beta. To use it, you must provide an App Password or a Workspace Token with Read/Write access to projects, repositories, and pull requests.

    When using Bitbucket Cloud, you must:

    1. Use the --org flag to specify the Bitbucket workspace.
    2. Use the --platform bitbucket_cloud flag.
    3. Specify the authentication method using the --auth-type flag (app-password or workspace-token).

    Limitations:

    • Reviewers: You cannot specify reviewers by username; you must use their UUID.
    • Projects: Specific project targeting is not yet supported; repositories will be modified within the workspace.
    • Forking: Using fork: true is experimental. If forking, you must use git-type: cmd to avoid inconsistent authorization errors. The forked repo will appear in a random project within your workspace.
    • Workspaces: Only a single workspace can be modified per command; additional values passed to --org are ignored.
    # Using App Password
export BITBUCKET_CLOUD_APP_PASSWORD="your_app_password"
multi-gitter run examples/go/upgrade-go-version.sh -u your_username --org "your_workspace" --repo "your_first_repository,your_second_repository" --platform bitbucket_cloud -m "your_commit_message" -B your_branch_name --auth-type app-password

# Using Workspace Token
export BITBUCKET_CLOUD_WORKSPACE_TOKEN="your_workspace_token"
multi-gitter run examples/go/upgrade-go-version.sh -u your_username --org "your_workspace" --repo "your_first_repository,your_second_repository" --platform bitbucket_cloud -m "your_commit_message" -B your_branch_name --auth-type workspace-token

  9. Configure authentication tokens

    master

    To list repositories and create pull requests, multi-gitter requires an access token. You can provide this token in two ways:

    1. Environment Variables: Set one of the following based on your provider:
      • GITHUB_TOKEN (for GitHub)
      • GITLAB_TOKEN (for GitLab)
      • GITEA_TOKEN (for Gitea)
    2. CLI Flag: Use the --token flag in your command.

    Provider Requirements

    • GitHub: Use a Personal Access Token (classic) with repo permissions.
    • GitLab: Use a Personal Access Token with api permissions.
    • Gitea: Generate tokens under Settings -> Applications -> Manage Access Tokens.

  11. Install multi-gitter

    master

    You can install multi-gitter using Homebrew, an automatic installation script, manual binary download, or from source using Go.

    Homebrew (Mac/Linux)

    brew install --cask lindell/multi-gitter/multi-gitter

    Automatic binary install

    curl -s https://raw.githubusercontent.com/lindell/multi-gitter/master/install.sh | sh

    Manual binary install

    Download the appropriate binary for your operating system from the GitHub releases page.

    From source

    Note: This is not recommended for most users.

    go install github.com/lindell/multi-gitter@latest

  12. Use the multi-gitter CLI

    master

    Multi-gitter is a tool designed for applying changes across multiple git repositories simultaneously. The CLI is invoked using the multi-gitter command and supports several subcommands to manage repository states and operations.

    Available subcommands include:

    • run: Execute operations across repositories.
    • status: Check the status of repositories.
    • merge: Perform merge operations.
    • close: Close repositories or tasks.
    • print: Print information or configuration.
    • version: Display the current version of multi-gitter.