Git Operations

/**
 * Git operations plugin for repository management
 * Handles commits, tags, pushes, and Git validation
 */
class Git extends Plugin {
  /**
   * Check if Git plugin should be enabled
   * @param options - Git plugin options
   * @returns Promise resolving to boolean indicating if Git repo exists
   */
  static isEnabled(options: any): Promise<boolean>;
  
  /** Initialize Git plugin with validation checks */
  init(): Promise<void>;
  
  /** Enable rollback functionality for Git operations */
  enableRollback(): void;
  
  /** Disable rollback functionality */
  disableRollback(): void;
  
  /** Rollback Git changes (delete tag, reset commits) */
  rollback(): void;
  
  /** Hook called before release - stage files and show changeset */
  beforeRelease(): Promise<void>;
  
  /**
   * Execute Git release operations (commit, tag, push)
   * @returns Promise resolving to boolean indicating if push was performed
   */
  release(): Promise<boolean>;
  
  /** Hook called after release - disable rollback */
  afterRelease(): void;
}

/**
 * Check if current branch matches required branch pattern
 * @param requiredBranch - Branch pattern or array of patterns (supports ! negation)
 * @returns Promise resolving to boolean
 */
isRequiredBranch(requiredBranch?: string | string[]): Promise<boolean>;

/**
 * Check if current branch has upstream tracking
 * @returns Promise resolving to boolean
 */
hasUpstreamBranch(): Promise<boolean>;

/**
 * Check if Git tag exists
 * @param tag - Tag name to check
 * @returns Promise resolving to boolean
 */
tagExists(tag: string): Promise<boolean>;

/**
 * Check if working directory is clean (no uncommitted changes)
 * @returns Promise resolving to boolean  
 */
isWorkingDirClean(): Promise<boolean>;

/**
 * Get number of commits since latest tag
 * @param commitsPath - Optional path to filter commits
 * @returns Promise resolving to commit count
 */
getCommitsSinceLatestTag(commitsPath?: string): Promise<number>;

/**
 * Stage specific files for commit
 * @param files - File path or array of file paths to stage
 * @returns Promise that resolves when staging completes
 */
stage(files: string | string[]): Promise<void>;

/**
 * Stage entire directory for commit
 * @param options - Staging options
 * @returns Promise that resolves when staging completes
 */
stageDir(options?: StageDirOptions): Promise<void>;

interface StageDirOptions {
  /** Base directory to stage (default: ".") */
  baseDir?: string;
}

/**
 * Reset/unstage files
 * @param files - File path or array of file paths to reset
 * @returns Promise that resolves when reset completes
 */
reset(files: string | string[]): Promise<void>;

/**
 * Get Git status showing staged/unstaged changes
 * @returns Promise resolving to Git status output
 */
status(): Promise<string>;

/**
 * Create Git commit
 * @param options - Commit options
 * @returns Promise that resolves when commit completes
 */
commit(options?: CommitOptions): Promise<void>;

interface CommitOptions {
  /** Commit message template (supports context interpolation) */
  message?: string;
  /** Additional arguments to pass to git commit */
  args?: string[];
}

/**
 * Create Git tag with annotation
 * @param options - Tag options
 * @returns Promise that resolves when tag is created
 */
tag(options?: TagOptions): Promise<void>;

interface TagOptions {
  /** Tag name (defaults to context tagName) */
  name?: string;
  /** Tag annotation template (supports context interpolation) */
  annotation?: string;
  /** Additional arguments to pass to git tag */
  args?: string[];
}

/**
 * Push commits and tags to remote repository
 * @param options - Push options
 * @returns Promise that resolves when push completes
 */
push(options?: PushOptions): Promise<void>;

/**
 * Get upstream arguments for push command
 * @param pushRepo - Repository URL or name
 * @returns Promise resolving to array of push arguments
 */
getUpstreamArgs(pushRepo?: string): Promise<string[]>;

/**
 * Get remote repository URL
 * @returns Promise resolving to remote URL
 */
getRemoteUrl(): Promise<string>;

/**
 * Get remote name for current branch
 * @returns Promise resolving to remote name
 */
getRemote(): Promise<string>;

/**
 * Get remote name for specific branch
 * @param branch - Branch name
 * @returns Promise resolving to remote name
 */
getRemoteForBranch(branch: string): Promise<string>;

/**
 * Get current Git branch name
 * @returns Promise resolving to branch name
 */
getBranchName(): Promise<string>;

/**
 * Get latest Git tag name
 * @returns Promise resolving to tag name
 */
getLatestTagName(): Promise<string>;

/**
 * Get second latest Git tag name
 * @param latestTag - Latest tag name
 * @returns Promise resolving to second latest tag name
 */
getSecondLatestTagName(latestTag: string): Promise<string>;

/**
 * Fetch from remote repository
 * @param remoteUrl - Remote URL to fetch from
 * @returns Promise that resolves when fetch completes
 */
fetch(remoteUrl: string): Promise<void>;

/**
 * Check if string is a remote name vs URL
 * @param remoteUrlOrName - String to check
 * @returns Boolean indicating if it's a remote name
 */
isRemoteName(remoteUrlOrName: string): boolean;

/**
 * Rollback tag push on remote (used in error scenarios)
 * @returns Promise that resolves when rollback completes
 */
rollbackTagPush(): Promise<void>;

interface PushOptions {
  /** Additional arguments to pass to git push */
  args?: string[];
}

interface GitOptions {
  /** Enable/disable Git plugin entirely */
  disabled?: boolean;
  
  /** Require clean working directory before release */
  requireCleanWorkingDir?: boolean;
  
  /** Required branch pattern (string or array, supports ! for negation) */
  requireBranch?: string | string[];
  
  /** Require upstream branch to be configured */
  requireUpstream?: boolean;
  
  /** Require commits since last tag */
  requireCommits?: boolean;
  
  /** Fail if no commits found (when requireCommits is true) */
  requireCommitsFail?: boolean;
  
  /** Path to check for commits (when requireCommits is true) */
  commitsPath?: string;
  
  /** Include untracked files when staging directory */
  addUntrackedFiles?: boolean;
  
  /** Enable commit creation */
  commit?: boolean;
  
  /** Commit message template (supports ${version}, ${changelog}, etc.) */
  commitMessage?: string;
  
  /** Additional arguments for git commit command */
  commitArgs?: string[];
  
  /** Enable Git tag creation */
  tag?: boolean;
  
  /** Tag annotation template (supports ${version}, ${changelog}, etc.) */
  tagAnnotation?: string;
  
  /** Additional arguments for git tag command */
  tagArgs?: string[];
  
  /** Enable push to remote repository */
  push?: boolean;
  
  /** Remote repository URL or name for push */
  pushRepo?: string;
  
  /** Additional arguments for git push command */
  pushArgs?: string[];
  
  /** Pattern to match tags for getLatestTagFromAllRefs */
  tagMatch?: string;
  
  /** Get latest tag from all refs instead of just current branch */
  getLatestTagFromAllRefs?: boolean;
}

// Basic Git operations configuration
const result = await runTasks({
  git: {
    requireCleanWorkingDir: true,
    commit: true,
    commitMessage: "Release ${version}",
    tag: true,
    tagAnnotation: "Release ${version}\\n\\n${changelog}",
    push: true
  }
});

// Advanced Git configuration with branch requirements
const result = await runTasks({
  git: {
    requireBranch: ["main", "master"],          // Must be on main or master
    requireUpstream: true,                      // Must have upstream configured
    requireCommits: true,                       // Must have commits since last tag
    addUntrackedFiles: true,                    // Include untracked files
    commit: true,
    commitMessage: "chore: release v${version}",
    commitArgs: ["--no-verify"],               // Skip pre-commit hooks
    tag: true,
    tagAnnotation: "Release ${version}",
    tagArgs: ["--sign"],                       // GPG sign tags
    push: true,
    pushArgs: ["--follow-tags"]                // Push tags with commits
  }
});

// Git configuration for feature branch releases
const result = await runTasks({
  git: {
    requireBranch: "!main",                    // Must NOT be on main branch
    requireUpstream: false,                    // Don't require upstream
    commit: true,
    commitMessage: "feat: ${version}",
    tag: false,                                // Don't create tags
    push: true,
    pushRepo: "origin"                         // Push to origin
  }
});

{
  "git": {
    "requireBranch": "main"              // Exact match
  }
}

{
  "git": {
    "requireBranch": ["main", "master"]  // Multiple allowed branches
  }
}

{
  "git": {
    "requireBranch": "!main"             // Must NOT be main
  }
}

{
  "git": {
    "requireBranch": ["develop", "!temp-*"]  // Must be develop, not temp-*
  }
}