### Install Multi-Gitter from Source

Source: https://github.com/lindell/multi-gitter/blob/master/README.md

Install multi-gitter directly from source using 'go install'. This method is generally not recommended for most users.

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

--------------------------------

### Typical Self-Hosted Gitea Setup

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

A common setup for self-hosted Gitea involves specifying the base URL and using an environment variable for the token.

```bash
--base-url https://gitea.internal --token $GITEA_TOKEN
```

--------------------------------

### Install Multi-Gitter via Homebrew

Source: https://github.com/lindell/multi-gitter/blob/master/README.md

Install multi-gitter on macOS or Linux using Homebrew for a convenient setup.

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

--------------------------------

### Run Multi-Gitter Command

Source: https://github.com/lindell/multi-gitter/blob/master/CONTRIBUTING.md

Example of how to run a multi-gitter command to execute a script across multiple repositories. Ensure you have Go installed and the repository cloned.

```sh
go run main.go run ./examples/general/replace.sh -R my-org/test-repo -m "Test message"
```

--------------------------------

### Example Set Git Configuration

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/git-interface.md

Demonstrates setting the 'user.email' configuration and logging the previous value. Handles potential errors during the operation.

```go
oldValue, err := git.SetConfig(ctx, "user.email", "bot@example.com")
if err != nil {
    log.Fatal(err)
}
log.Printf("Previous email: %s", oldValue)
```

--------------------------------

### Add a JavaScript Example

Source: https://github.com/lindell/multi-gitter/blob/master/examples/README.md

Contribute your JavaScript script example by adding it to the corresponding language folder. Ensure it includes a 'Title: xxx' comment.

```javascript
// Title: My js script that does X
```

--------------------------------

### Add a Bash Example

Source: https://github.com/lindell/multi-gitter/blob/master/examples/README.md

Contribute your bash script example by adding it to the corresponding language folder. Ensure it includes a 'Title: xxx' comment.

```bash
# Title: My bash script that does X
```

--------------------------------

### Example YAML Configuration File

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/configuration.md

This is an example of a Multi-gitter configuration file in YAML format. It specifies the platform, organizations to target, branch name, commit message, and concurrency settings.

```yaml
platform: github
org:
  - my-organization
branch: feature-branch
commit-message: "Update dependencies"
concurrent: 4
dry-run: false
```

--------------------------------

### Typical Bitbucket Server Configuration

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

Example configuration for connecting to a Bitbucket Server instance with a specified base URL, username, and platform.

```bash
--base-url https://bitbucket.internal \
-u bot-user \
--platform bitbucket_server
```

--------------------------------

### Install Multi-Gitter Automatically

Source: https://github.com/lindell/multi-gitter/blob/master/README.md

Automatically install the latest version of multi-gitter by running a curl command piped to sh.

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

--------------------------------

### Typical Gerrit Configuration

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

Example configuration for connecting to a Gerrit instance using a token, base URL, and specifying the platform.

```bash
--base-url https://gerrit.internal \
--token $GERRIT_TOKEN \
--platform gerrit
```

--------------------------------

### Execute Runner Example

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/runner.md

Demonstrates how to instantiate and run the multi-gitter runner. Ensure the VersionController is properly initialized and the script path is absolute.

```go
runner := &multigitter.Runner{
    VersionController: versionController,
    ScriptPath:       "/absolute/path/to/script.sh",
    FeatureBranch:    "feature-branch",
    CommitMessage:    "Update dependencies",
    Concurrent:       4,
}

err := runner.Run(context.Background())
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Example Script for Manual Commit Mode

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/advanced-features.md

An example bash script demonstrating how to handle multiple commits within a script when using multi-gitter's manual commit mode.

```bash
#!/bin/bash

# Script handles its own commits

git config user.email "bot@example.com"
git config user.name "Auto Bot"

# Create first commit
echo "changes1" > file1.txt
git add file1.txt
git commit -m "First change"

# Create second commit
echo "changes2" > file2.txt
git add file2.txt
git commit -m "Second change"

# Both commits are included in the PR

```

--------------------------------

### Full Example Workflow for Git Operations

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/changes.md

Demonstrates a complete workflow from detecting changes to committing and pushing them. Includes logging and error handling.

```go
// After script execution
changes, err := git.Diff(ctx)
if err != nil {
    log.Fatal(err)
}

// Check if there are changes
if len(changes.Additions) == 0 && len(changes.Deletions) == 0 {
    fmt.Println("No changes detected")
    return nil
}

// Log changes
for file := range changes.Additions {
    log.Printf("Added/Modified: %s", file)
}
for _, file := range changes.Deletions {
    log.Printf("Deleted: %s", file)
}

// Set commit message
changes.Message = "Automated update via multi-gitter"

// Create commit with changes
commitAuthor := &git.CommitAuthor{
    Name:  "Bot User",
    Email: "bot@example.com",
}

err = git.Commit(ctx, commitAuthor, changes.Message)
if err != nil {
    log.Fatal(err)
}

// Push changes
err = git.Push(ctx, "feature-branch", false, nil)
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Filter Repositories Example

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/filtering.md

Demonstrates how to apply multiple repository filters, including skipping exact repository names, including repositories matching a regex, and excluding repositories matching another regex. Repositories must pass all filters to be included.

```go
repos := []scm.Repository{
    // ...
}

filters := multigitter.RepoFilters{
    SkipRepository: []string{"owner/archived"},
    RegExIncludeRepository: regexp.MustCompile(`^owner/api-.*`),
    RegExExcludeRepository: regexp.MustCompile(`-experimental$`),
}

filtered := filterRepositories(repos, filters)
```

--------------------------------

### Example YAML Configuration

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/commands.md

This snippet shows a basic structure for a multi-gitter YAML configuration file. It specifies the platform, organizations to target, a branch for operations, concurrency level, and log level.

```yaml
platform: github
org:
  - my-organization
branch: feature-branch
concurrent: 4
log-level: info
```

--------------------------------

### Select Git Implementation

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/advanced-features.md

Choose between the default pure Go implementation (`go-git`) or the system's command-line Git (`cmd`) using the `--git-type` flag. The `go-git` implementation is cross-platform and has no external dependencies, while `cmd` requires a system Git installation and is necessary for interactive modes.

```bash
multi-gitter run script.sh --git-type go   # Default, pure Go
```

```bash
multi-gitter run script.sh --git-type cmd  # System git command
```

--------------------------------

### Automated CI/CD Integration with Dynamic Strategy

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/conflict-strategy.md

Example of a reusable script for CI/CD that uses an environment variable to determine the conflict strategy.

```bash
#!/bin/bash

# Reusable script that runs in CI

STRATEGY=${CONFLICT_STRATEGY:-skip}

multi-gitter run $SCRIPT_PATH \
  --org myorg \
  --branch ci/automated-changes \
  --conflict-strategy $STRATEGY \
  --concurrent 4
```

--------------------------------

### Handling Git Clone Errors

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/errors.md

If git is not found when using `--git-type=cmd`, install git or switch to the default `--git-type=go`.

```bash
# Install git: apt install git (Linux), brew install git (macOS)
# OR use default: --git-type=go (no installation required)
```

--------------------------------

### Commit Author Validation - Valid Example

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/commit-author.md

Demonstrates the correct way to set both author name and email flags.

```bash
--author-name "Bot" --author-email "bot@example.com"
```

--------------------------------

### Handle Diff Changes

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/git-interface.md

Example of how to process the Changes structure returned by the Diff function. Iterates through additions and deletions to log modified and deleted files.

```go
changes, err := git.Diff(ctx)
if err != nil {
    log.Fatal(err)
}
for path := range changes.Additions {
    log.Printf("Modified: %s", path)
}
for _, path := range changes.Deletions {
    log.Printf("Deleted: %s", path)
}
```

--------------------------------

### CreatePullRequest Example

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/version-controller.md

Demonstrates how to create a new pull request with details like title, body, head and base branches, and reviewers. Ensure the `newPR` struct is populated correctly before calling.

```go
newPR := scm.NewPullRequest{
    Title:     "Update dependencies",
    Body:      "Automated dependency update",
    Head:      "feature-branch",
    Base:      "main",
    Reviewers: []string{"alice", "bob"},
    Draft:     false,
}

pr, err := vc.CreatePullRequest(ctx, repo, repo, newPR)
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Common Regex Patterns for Repository Filtering

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/filtering.md

Examples of common regular expression patterns used to match repositories by prefix or suffix.

```regex
^owner/api-           # owner/api-*, owner/api-*, etc.
^team-                # team-*, team-core, etc.
```

```regex
-sdk$                 # something-sdk
-deprecated$          # anything-deprecated
```

```regex
^(api|lib|core)-      # api-*, lib-*, core-*
-(beta|experimental)$ # *-beta or *-experimental
```

--------------------------------

### Create a New Pull Request Instance

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/scm-core.md

Example of initializing a NewPullRequest struct with specific values for creating a pull request. Includes details like title, branches, reviewers, and auto-merge settings.

```go
newPR := scm.NewPullRequest{
    Title:     "Update dependencies",
    Body:      "This PR updates all dependencies to their latest versions.\n\nSee CHANGELOG for details.",
    Head:      "feature/update-deps",
    Base:      "main",
    Reviewers: []string{"alice", "bob"},
    Assignees: []string{"charlie"},
    Draft:     false,
    AutoMerge: true,
    Labels:    []string{"dependencies", "automation"},
}
```

--------------------------------

### Commit Author Validation - Invalid Examples

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/commit-author.md

Shows invalid configurations where only one of author-name or author-email is provided, which will result in an error.

```bash
# Invalid - will error
--author-name "Bot"  # Missing email
--author-email "bot@example.com"  # Missing name
```

--------------------------------

### Scheduled Daily Updates with Replace Strategy

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/conflict-strategy.md

Example of a daily script that ensures the latest changes are reflected by using the 'replace' conflict strategy.

```bash
#!/bin/bash

# Run daily at 2 AM, always use replace strategy
# to ensure latest changes are reflected

multi-gitter run /scripts/update-deps.sh \
  --org myorg \
  --branch automated/deps-update \
  --conflict-strategy replace \
  --pr-auto-merge
```

--------------------------------

### Example Usage of RepoContainsTopic

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/scm-core.md

Demonstrates how to use the RepoContainsTopic function to check if a repository matches a given set of topics. Returns true if any filter topic is found.

```go
repoTopics := []string{"golang", "cli", "automation"}
filterTopics := []string{"cli", "python"}
if scm.RepoContainsTopic(repoTopics, filterTopics) {
    log.Println("Repository matches filter")
}
// Result: true (because "cli" matches)
```

--------------------------------

### Skip CI and Set Commit Message

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/advanced-features.md

An example demonstrating how to skip CI/CD pipelines and set a custom commit message during a push operation, useful for formatting changes.

```bash
multi-gitter run format-script.sh \
  --push-option ci.skip \
  --commit-message "Auto-format code"
```

--------------------------------

### Loading Multiple Configuration Files

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/commands.md

Illustrates how to load multiple configuration files, where later files override settings from earlier ones. This is useful for applying base configurations and then overriding specific settings.

```bash
multi-gitter run script.sh --config base.yaml --config override.yaml
```

--------------------------------

### Get Remote URL

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/git-interface.md

Retrieves the remote URL of the repository. Requires a context for cancellation and timeouts.

```go
func (g Git) GetRemoteURL(ctx context.Context) (string, error)
```

--------------------------------

### VersionControllerRemoteReference

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/version-controller.md

Optional interface to get the remote reference string, typically used for push operations.

```APIDOC
## RemoteReference

### Description
Retrieves the remote reference string, which is often used in Git operations for pushing branches or creating pull requests.

### Method
RemoteReference

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **baseBranch** (string) - Required - The name of the base branch.
- **featureBranch** (string) - Required - The name of the feature branch.
- **skipPullRequest** (bool) - Optional - If true, skip the creation of a pull request.
- **pushOnly** (bool) - Optional - If true, indicates that only a push operation is intended.

### Response
#### Success Response
- **string** - The formatted remote reference string.
```

--------------------------------

### Get Current Branch Name

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/git-interface.md

Retrieves the name of the currently checked out branch. Requires a context for cancellation and timeouts.

```go
func (g Git) GetCurrentBranchName(ctx context.Context) (string, error)
```

--------------------------------

### PullRequest Interface

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/types.md

Represents an existing pull request, providing methods to check its status and get a string representation.

```APIDOC
## PullRequest Interface

### Description
Represents an existing pull request.

### Methods
- `Status()` - Returns the current status of the pull request
- `String()` - Returns a string representation of the pull request

### Implementations
GitHub PullRequest, GitLab MergeRequest, Gitea PullRequest, Bitbucket PullRequest, Gerrit Change
```

--------------------------------

### Runner Run Method

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/runner.md

Executes the runner with configured settings. Fetches repositories, runs a script in each, and manages pull requests. Requires a configured VersionController, script path, and other options.

```go
func (r *Runner) Run(ctx context.Context) error
```

--------------------------------

### Get Previous Commit Hash

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/git-interface.md

Returns the git commit hash of the current HEAD or the previous commit before changes were made.

```go
func (g Git) GetPreviousCommit(ctx context.Context) (string, error)
```

--------------------------------

### GetRepositories Method Signature

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/version-controller.md

Fetches all repositories matching the configured filters. Use this to discover available repositories based on predefined criteria.

```go
func (vc VersionController) GetRepositories(ctx context.Context) ([]scm.Repository, error)
```

--------------------------------

### Authenticate with Bitbucket Server

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

Set the Bitbucket Server access token as an environment variable and run Multi-Gitter with authentication details.

```bash
export BITBUCKET_SERVER_TOKEN=...
multi-gitter run script.sh \
  -u username \
  --base-url https://bitbucket.example.com \
  --platform bitbucket_server
```

--------------------------------

### Configure Bitbucket Cloud Platform

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

Use the `--platform bitbucket_cloud` flag to specify Bitbucket Cloud as the target platform. This is a beta feature.

```bash
--platform bitbucket_cloud
```

--------------------------------

### Manual Feature Development with Skip and Replace

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/conflict-strategy.md

Demonstrates a workflow for manual feature development, first testing with 'skip' and 'dry-run', then applying 'replace' after review.

```bash
#!/bin/bash

# First run - creates branch and PR
multi-gitter run /scripts/refactor.sh \
  --org myorg \
  --branch feature/refactor \
  --conflict-strategy skip \
  --dry-run  # Test first

# After review, run again to update
multi-gitter run /scripts/refactor.sh \
  --org myorg \
  --branch feature/refactor \
  --conflict-strategy replace \
  --commit-message "Address code review feedback"
```

--------------------------------

### Connect to Self-Hosted Bitbucket Server Instance

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/advanced-features.md

Configure Multi-Gitter to connect to a self-hosted Bitbucket Server instance by specifying the platform type and the custom base URL.

```bash
multi-gitter run script.sh --platform bitbucket-server --base-url https://bitbucket.example.com
```

--------------------------------

### Enable Trace Logging

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/errors.md

For even more granular detail, use `--log-level=trace` to capture all API calls, response bodies, and internal state changes.

```bash
multi-gitter run script.sh --log-level=trace
```

--------------------------------

### Get Open Pull Request

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/version-controller.md

Retrieves an open pull request for a specific repository and branch. Returns an error if no open PR exists.

```Go
func (vc VersionController) GetOpenPullRequest(
    ctx context.Context, 
    repo scm.Repository, 
    branchName string) (scm.PullRequest, error)
```

```Go
pr, err := vc.GetOpenPullRequest(ctx, repo, "feature-branch")
if err != nil {
    // No open PR exists
    log.Println("No open PR found")
}
```

--------------------------------

### Gitea Authentication with Token

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

Set the GITEA_TOKEN environment variable for authentication. Then, run Multi-Gitter with your script and organization.

```bash
export GITEA_TOKEN=...
multi-gitter run script.sh --org myorg
```

--------------------------------

### Run Script on Multiple Platforms

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

This script iterates through GitHub, GitLab, and Gitea, executing a given script for each platform. It uses environment variables for authentication tokens, dynamically named after the platform (e.g., GITHUB_TOKEN). Ensure the script path and organization are provided as arguments.

```bash
#!/bin/bash

SCRIPT=$1
ORG=$2
BRANCH=${3:-feature-branch}

for PLATFORM in github gitlab gitea;
  do
    echo "Running on $PLATFORM..."
    multi-gitter run $SCRIPT \
      --platform $PLATFORM \
      --org $ORG \
      --branch $BRANCH \
      --token $(eval echo \
$${PLATFORM^^}_TOKEN)
done

```

--------------------------------

### Get Changes using Diff Operation

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/changes.md

Retrieves detected file changes using the git Diff operation. Ensure proper error handling.

```go
changes, err := git.Diff(ctx)
if err != nil {
    return err
}
```

--------------------------------

### Update npm Dependency if Exists

Source: https://github.com/lindell/multi-gitter/blob/master/README.md

Updates a specified npm package to a new version if it is already listed in the `package.json`. It checks for the existence of `package.json` and the package itself before installing.

```bash
#!/bin/bash

### Change these values ###
PACKAGE=webpack
VERSION=4.43.0

if [ ! -f "package.json" ]; then
    echo "package.json does not exist"
    exit 1
fi

# Check if the package already exist (without having to install all packages first), abort if it does not
current_version=`jq ".dependencies[\"$PACKAGE\"]" package.json`
if [ "$current_version" == "null" ];
then
    echo "Package \"$PACKAGE\" does not exist"
    exit 2
fi

npm install --save $PACKAGE@$VERSION
```

--------------------------------

### Multi-Gitter CLI Options

Source: https://github.com/lindell/multi-gitter/blob/master/README.md

These are command-line options for the Multi-Gitter tool. Use `--topic` to filter by repository topic or `-U`/`--user` to target repositories owned by a specific user. The `-u`/`--username` flag is for Bitbucket server authentication.

```bash
--topic strings           The topic of a GitHub/GitLab/Gitea repository. All repositories having at least one matching topic are targeted.
  -U, --user strings            The name of a user. All repositories owned by that user will be used.
  -u, --username string         The Bitbucket server username.
```

--------------------------------

### Connect to Self-Hosted GitHub Enterprise Instance

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/advanced-features.md

Configure Multi-Gitter to connect to a self-hosted GitHub Enterprise instance by specifying the platform type and the custom base URL.

```bash
multi-gitter run script.sh --platform github-enterprise --base-url https://github.enterprise.com
```

--------------------------------

### Git Configuration Fallback Example

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/commit-author.md

When the CommitAuthor is not specified, multi-gitter falls back to using global git configuration settings for the author's name and email.

```bash
# No --author-name or --author-email specified
# Uses git config settings

git config --global user.name "Default Name"
git config --global user.email "default@example.com"

multi-gitter run script.sh
# Uses "Default Name <default@example.com>"
```

--------------------------------

### Run Script in Interactive Mode

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/advanced-features.md

Use interactive mode to get confirmation before committing changes in each repository. Requires `--git-type=cmd` and `--concurrent` set to 1.

```bash
multi-gitter run script.sh --interactive
```

--------------------------------

### Run Script with Config File Flag

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/README.md

Execute a script using a specified configuration file via the --config flag. This method has medium priority.

```bash
multi-gitter run script.sh --config config.yaml
```

--------------------------------

### Update Go Module Version

Source: https://github.com/lindell/multi-gitter/blob/master/README.md

Updates a specified Go module to a new version. It first checks if the module exists and then uses `go get` to perform the update.

```bash
#!/bin/bash

### Change these values ###
MODULE=github.com/go-git/go-git/v5
VERSION=v5.1.0

# Check if the module already exist, abort if it does not
go list -m $MODULE &> /dev/null
status_code=$?
if [ $status_code -ne 0 ]; then
    echo "Module \"$MODULE\" does not exist"
    exit 1
fi

go get $MODULE@$VERSION
```

--------------------------------

### Run Script with Specified Fork Owner

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/advanced-features.md

Execute a script using the fork workflow, specifying a particular organization to create the fork in. This allows for better organization of forks in multi-organization setups.

```bash
multi-gitter run script.sh --fork --fork-owner myorg
```

--------------------------------

### Execute Script in Multiple Repositories with Multi-Gitter Print

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/commands.md

The 'print' command clones repositories, executes a specified script within each, and captures the output. It does not commit or push changes. Ensure the script path is executable.

```bash
multi-gitter print ./list-files.sh \
  --org my-organization \
  --concurrent 4 \
  --output results.txt
```

--------------------------------

### Self-Hosted Gitea Configuration

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

Configure Multi-Gitter to connect to a self-hosted Gitea instance by providing the `--base-url` and `--platform gitea` flags.

```bash
multi-gitter run script.sh \
  --base-url https://gitea.example.com \
  --platform gitea
```

--------------------------------

### Runner.Run

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/runner.md

Executes the runner with the configured settings. It fetches repositories from the version controller, executes the script in each one, and creates/updates pull requests based on the changes.

```APIDOC
## Runner.Run

### Description
This is the main entry point for executing the runner. It fetches repositories, applies filters, clones them, executes a script, detects changes, commits, and creates/updates pull requests, handling conflicts.

### Method
`Run`

### Parameters
#### Context
- **ctx** (context.Context) - Required - Context for cancellation and timeouts

### Returns
- **error** - Error if the run fails

### Example
```go
runner := &multigitter.Runner{
    VersionController: versionController,
    ScriptPath:       "/absolute/path/to/script.sh",
    FeatureBranch:    "feature-branch",
    CommitMessage:    "Update dependencies",
    Concurrent:       4,
}

err := runner.Run(context.Background())
if err != nil {
    log.Fatal(err)
}
```
```

--------------------------------

### Iterate Through Added or Modified Files

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/changes.md

Loops through the Additions map to process each modified file's path and content.

```go
for filepath, content := range changes.Additions {
    fmt.Printf("Modified: %s (%d bytes)\n", filepath, len(content))
}
```

--------------------------------

### Set Bitbucket Server Platform

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

Specify the Bitbucket Server platform for Multi-Gitter operations.

```bash
--platform bitbucket_server
```

--------------------------------

### GitLab Platform Usage

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

Specify GitLab as the platform using the --platform flag.

```bash
--platform gitlab
```

--------------------------------

### GitHub Platform Usage

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

Specify GitHub as the platform using the --platform flag.

```bash
--platform github
```

--------------------------------

### GitLab Self-Hosted Support

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

Configure multi-gitter to use a self-hosted GitLab instance by specifying the --base-url and --platform flags.

```bash
multi-gitter run script.sh \
  --base-url https://gitlab.example.com \
  --platform gitlab
```

--------------------------------

### Run Script with Command-line Flags

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/README.md

Execute a script using command-line flags for organization and commit message. This method has the highest priority for configuration.

```bash
multi-gitter run script.sh --org myorg -m "Message"
```

--------------------------------

### Filters with Repository Search and Skip Forks

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/filtering.md

Apply filters after repository search results are obtained. The --skip-forks flag is also demonstrated.

```bash
multi-gitter run script.sh \
  --repo-search "language:go stars:>100" \
  --repo-exclude "archived" \
  --skip-forks
```

--------------------------------

### Configure Gitea Platform

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

Use the `--platform gitea` flag to specify Gitea as the target platform. This is typically used when running Multi-Gitter commands.

```bash
--platform gitea
```

--------------------------------

### Fork Repository

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/version-controller.md

Creates a fork of the repository under a specified owner. If newOwner is empty, the fork is created under the authenticated user's account. Errors can occur due to existing forks, permissions, or rate limits.

```Go
func (vc VersionController) ForkRepository(
    ctx context.Context, 
    repo scm.Repository, 
    newOwner string) (scm.Repository, error)
```

--------------------------------

### Connect to Self-Hosted Gerrit Instance

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/advanced-features.md

Configure Multi-Gitter to connect to a self-hosted Gerrit instance by specifying the platform type and the custom base URL.

```bash
multi-gitter run script.sh --platform gerrit --base-url https://gerrit.example.com
```

--------------------------------

### Include Repositories by Regex Pattern

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/filtering.md

Only include repositories that match a specified regular expression pattern using the --repo-include flag.

```bash
multi-gitter run script.sh \
  --org my-org \
  --repo-include "^owner/api-.*"
```

--------------------------------

### Clone Repositories with Folder Structure

Source: https://github.com/lindell/multi-gitter/blob/master/README.md

Clones all repositories locally, preserving their group folder structure. This script is intended to be used with the 'print' command.

```bash
#!/bin/bash

# This script should be used with the print command.
mkdir -p ~/multi-gitter/$REPOSITORY
cp -r . ~/multi-gitter/$REPOSITORY
```

--------------------------------

### Autocompletion for Repositories

Source: https://github.com/lindell/multi-gitter/blob/master/internal/scm/README.md

Optional function to support shell-autocompletion for repository names. Automatically used for tab completions when activated.

```go
func GetAutocompleteRepositories(ctx context.Context, search string) ([]string, error)
```

--------------------------------

### Run Script with Bitbucket Cloud Workspace Token Auth

Source: https://github.com/lindell/multi-gitter/blob/master/README.md

Execute a script across multiple repositories in a Bitbucket Cloud workspace using workspace token authentication. Set the BITBUCKET_CLOUD_WORKSPACE_TOKEN environment variable before running.

```shell
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
```

--------------------------------

### GitHub Enterprise Support

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

Configure multi-gitter to use a GitHub Enterprise instance by specifying the --base-url and --platform flags.

```bash
multi-gitter run script.sh \
  --base-url https://github.enterprise.com \
  --platform github
```

--------------------------------

### Run a Shell Script with Multi-Gitter

Source: https://github.com/lindell/multi-gitter/blob/master/README.md

Execute a shell script across multiple repositories. Ensure the script has execute permissions before running.

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

--------------------------------

### Search Repositories by Topic

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/advanced-features.md

Use the `--repo-search` flag with GitHub-specific syntax to find repositories based on topics, star count, and other criteria. This is useful for targeting specific types of projects.

```bash
multi-gitter run script.sh --repo-search "topic:golang stars:>100"
```

```bash
--repo-search "language:go stars:>1000 is:public"
```

```bash
--repo-search "archived:true"
```

--------------------------------

### Run with SSH Authentication

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/advanced-features.md

Execute Multi-Gitter commands using SSH key authentication. Ensure SSH keys are configured locally and added to your Git provider, and that the repository is accessible via SSH.

```bash
multi-gitter run script.sh --ssh-auth
```

--------------------------------

### Skip Specific Repositories

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/filtering.md

Skip one or more repositories by providing their exact names using the --skip-repo flag.

```bash
multi-gitter run script.sh \
  --org my-org \
  --skip-repo owner/archived \
  --skip-repo owner/deprecated
```

--------------------------------

### Run Interpreted Scripts with Multi-Gitter

Source: https://github.com/lindell/multi-gitter/blob/master/README.md

Execute interpreted scripts (Python, Node.js, Go) by specifying the absolute path using $PWD. This ensures the script runs correctly within each repository's context.

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

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

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

--------------------------------

### Set Git Configuration

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/git-interface.md

Sets a local git configuration value, such as user name or email. Returns the previous value if one existed. Requires a context, configuration name, and value.

```go
func (g Git) SetConfig(ctx context.Context, name string, value string) (string, error)
```

--------------------------------

### Diff Working Directory Changes

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/git-interface.md

Retrieves a summary of changes in the working directory, including additions and deletions. Requires a context for cancellation and timeouts.

```go
func (g Git) Diff(ctx context.Context) (Changes, error)
```

--------------------------------

### Check GitHub Token

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/README.md

Verify that your GitHub token is correctly set in the environment by echoing the GITHUB_TOKEN variable. This is a common troubleshooting step for authentication failures.

```bash
echo $GITHUB_TOKEN
```

--------------------------------

### Repository FullName Method

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/scm-core.md

Retrieves the full identifier of a repository in the format 'owner/name'.

```go
func (r Repository) FullName() string
```

--------------------------------

### Generate and Add SSH Key

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/advanced-features.md

Steps to generate a new SSH key pair, add it to the ssh-agent, and configure it with your Git provider. Includes a test command to verify SSH connection.

```bash
# Generate SSH key (if not exists)
ssh-keygen -t ed25519

# Add key to ssh-agent
ssh-add ~/.ssh/id_ed25519

# Add public key to GitHub/GitLab

# Test connection
ssh -T git@github.com
```

--------------------------------

### Authenticate with Gerrit

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/platforms.md

Set the Gerrit HTTP token as an environment variable and run Multi-Gitter with the base URL and platform.

```bash
export GERRIT_TOKEN=...
multi-gitter run script.sh \
  --base-url https://gerrit.example.com \
  --platform gerrit
```

--------------------------------

### Set Conflict Strategy in Configuration File

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/conflict-strategy.md

Configure the default conflict strategy in your Multi-Gitter configuration file.

```yaml
conflict-strategy: replace
```

--------------------------------

### Checkout

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/git-interface.md

Switches the working directory to the specified branch. The branch must already exist.

```APIDOC
## Checkout

### Description
Checks out an existing branch.

### Method
`Checkout`

### Parameters
- **ctx** (context.Context) - Context for cancellation and timeouts
- **branch** (string) - Name of the branch to check out

### Returns
- **error** - Error if checkout fails

### Errors:
- Branch not found errors if the branch doesn't exist
- Merge conflict errors if there are uncommitted changes
```

--------------------------------

### Update File Content in Additions Map

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/changes.md

Shows how to set or update the content of a file within the Additions map.

```go
// File content is the entire file
changes.Additions["path/to/file.txt"] = []byte("new content here")

// For large files, content can be significant
largeFile := changes.Additions["large.bin"]
fmt.Printf("File size: %d bytes\n", len(largeFile))
```

--------------------------------

### Specify Clone Directory

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/advanced-features.md

Control where repositories are cloned. Use `--clone-dir` for performance (e.g., SSD), persistence (e.g., debugging), or custom storage locations. Repositories are automatically cleaned up unless a persistent directory is specified.

```bash
multi-gitter run script.sh --clone-dir /tmp/repos
```

--------------------------------

### Run Script in Multiple Repositories

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/commands.md

Executes a script in multiple repositories, clones them, creates branches, and optionally pushes changes and creates pull requests. Use when you need to automate changes across many repositories.

```bash
Usage:
  multi-gitter run [script path] [flags]

Arguments:
  script path - Path to the executable script or interpreter command
```

```bash
multi-gitter run ./update-deps.sh \
  --org my-organization \
  --branch feature/update-deps \
  --commit-message "Update dependencies" \
  --concurrent 4
```

--------------------------------

### Diff

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/git-interface.md

Retrieves a summary of changes in the working directory.

```APIDOC
## Diff

### Description
Retrieves a summary of changes in the working directory.

### Method
(Implicitly a method call on a Git object)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Returns
- Changes: Structure containing additions, deletions, and commit info
- error: Error if diff fails

### Response Example
```json
{
  "Additions": {
    "file1.txt": "new content"
  },
  "Deletions": [
    "file2.txt"
  ],
  "OldHash": "abcdef123456",
  "Message": ""
}
```
```

--------------------------------

### Combine Multiple Filters

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/filtering.md

Use multiple filtering flags together to create a precise selection of repositories. Filters are applied in order: include, exclude, then skip.

```bash
multi-gitter run script.sh \
  --org my-org \
  --repo-include "^owner/(api|lib)-" \
  --repo-exclude "-beta$" \
  --skip-repo owner/api-internal
```

--------------------------------

### Use fork workflow for script execution

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/README.md

Run a script using a fork workflow, specifying the owner of the fork.

```bash
multi-gitter run ./script.sh --fork --fork-owner myteam
```

--------------------------------

### Multi-Gitter Configuration Options

Source: https://github.com/lindell/multi-gitter/blob/master/README.md

This YAML block lists all available configuration options for multi-gitter. It covers settings for API pushes, assignees, authentication, commit details, branching, cloning, code search, concurrency, conflict resolution, draft pull requests, dry runs, fetch depth, forking, Git implementation type, organization and group targeting, logging, manual commits, review randomization, merge types, and output formatting.

```yaml
# Push changes through the API instead of git. Only supported for GitHub.
# It has the benefit of automatically producing verified commits. However, it is slower and not suited for changes to large files.
api-push: false

# The username of the assignees to be added on the pull request.
assignees:
  - example

# The authentication type. Used only for Bitbucket cloud. Available values: app-password, workspace-token.
auth-type: app-password

# Email of the committer. If not set, the global git config setting will be used.
author-email: 

# Name of the committer. If not set, the global git config setting will be used.
author-name: 

# The branch which the changes will be based on.
base-branch: 

# Base URL of the target platform, needs to be changed for GitHub enterprise, a self-hosted GitLab instance, Gitea or BitBucket, Gerrit.
base-url: 

# The name of the branch where changes are committed.
branch: multi-gitter-branch

# The temporary directory where the repositories will be cloned. If not set, the default os temporary directory will be used.
clone-dir: 

# Use a code search to find a set of repositories to target (GitHub only). Repeated results from a given repository will be ignored, forks are NOT included by default (use `fork:true` to include them). See the GitHub documentation for full syntax: https://docs.github.com/en/search-github/searching-on-github/searching-code.
code-search: 

# The commit message. Will default to title + body if none is set.
commit-message: 

# The maximum number of concurrent runs.
concurrent: 1

# What should happen if the branch already exist.
# Available values:
#   skip: Skip making any changes to the existing branch and do not create a new pull request.
#   replace: Replace the existing content of the branch by force pushing any new changes, then reuse any existing pull request, or create a new one if none exist.
conflict-strategy: skip

# Create pull request(s) as draft.
draft: false

# Run without pushing changes or creating pull requests.
dry-run: false

# Limit fetching to the specified number of commits. Set to 0 for no limit.
fetch-depth: 1

# Fork the repository instead of creating a new branch on the same owner.
fork: false

# If set, make the fork to the defined value. Default behavior is for the fork to be on the logged in user.
fork-owner: 

# The type of git implementation to use.
# Available values:
#   go: Uses go-git, a Go native implementation of git. This is compiled with the multi-gitter binary, and no extra dependencies are needed.
#   cmd: Calls out to the git command. This requires git to be installed and available with by calling "git".
git-type: go

# The name of a GitLab organization. All repositories in that group will be used.
group:
  - example

# Include GitLab subgroups when using the --group flag.
include-subgroups: false

# Insecure controls whether a client verifies the server certificate chain and host name. Used only for Bitbucket server.
insecure: false

# Take manual decision before committing any change. Requires git to be installed.
interactive: false

# Labels to be added to any created pull request.
labels:
  - example

# The file where all logs should be printed to. "-" means stdout.
log-file: "-"

# The formatting of the logs. Available values: text, json, json-pretty.
log-format: text

# The level of logging that should be made. Available values: trace, debug, info, error.
log-level: info

# Let the script commit the changes, multiple commits are allowed, multi-gitter will still open a pull request when changes are detected.
manual-commit: false

# If this value is set, reviewers will be randomized.
max-reviewers: 0

# If this value is set, team reviewers will be randomized
max-team-reviewers: 0

# The type of merge that should be done (GitHub/Gitea). Multiple types can be used as backup strategies if the first one is not allowed. The first type is used for auto-merge.
merge-type:
  - merge
  - squash
  - rebase

# The name of a GitHub organization. All repositories in that organization will be used.
org:
  - example

# The file that the output of the script should be outputted to. "-" means stdout.
output: "-"

# Don't use any terminal formatting when printing the output.
plain-output: false

```

--------------------------------

### Repository Interface Definition

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/types.md

Defines the core methods for interacting with a git repository. Implementations provide platform-specific details.

```go
type Repository interface {
    CloneURL() string
    DefaultBranch() string
    FullName() string
}
```

--------------------------------

### Fix Linting Problems in Go Repositories

Source: https://github.com/lindell/multi-gitter/blob/master/README.md

Runs `golangci-lint` to automatically fix linting issues in all Go files within the specified directories.

```bash
#!/bin/bash

golangci-lint run ./... --fix
```

--------------------------------

### Iterate Through Deleted Files

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/api-reference/changes.md

Loops through the Deletions slice to process each file path that was removed.

```go
for _, filepath := range changes.Deletions {
    fmt.Printf("Deleted: %s\n", filepath)
}
```

--------------------------------

### Run a script across an organization

Source: https://github.com/lindell/multi-gitter/blob/master/_autodocs/README.md

Execute a script in multiple repositories within a specified organization. Requires a script path, organization name, and a commit message.

```bash
multi-gitter run ./update.sh --org myorg -m "Update dependencies"
```