GitLegends Overview

GitLegends is an open-source command-line tool that allows you to automate and simulate historical Git repository activity by creating backdated commits, branches, pull requests, and merges. In other words, you can make a repository appear as if it evolved over months or years, with commits and merge events carrying dates in the past. GitLegends leverages standard tools like Git and the GitHub CLI (gh) to orchestrate these actions, enabling a realistic project history on GitHub.

GitLegends is especially useful for demonstration projects, educational scenarios, or any situation where you want to recreate a timeline of development. By specifying custom dates for each commit and merge, you can fill a repository's history with meaningful events that took place at those times. For example, you could simulate a year's worth of feature development, bug fixes, and releases in a repository, all in one sitting.

Key Features

• Backdated Initial Commits: Create a new repository with an initial commit dated in the past (e.g. last year). The tool initializes a local Git repo, makes the first commit with your chosen date, and uses gh to create the remote GitHub repo with that commit already pushed.
• Simulated Branch "Birth": Start a new branch and mark its creation with a backdated empty commit (a commit with no changes) at a specified date. This gives the branch a historical starting point in the timeline.
• Historical Commits on Branches: Commit changes to any branch using a past date/time. GitLegends supports adding normal changes or even making an empty commit. You can easily backdate feature implementation commits, bug fixes, or any work, specifying exact timestamps for each commit.
• Pull Request Orchestration: Open pull requests via the GitHub CLI to simulate code review workflow. While the PR itself will have the current timestamp on GitHub, it ties together the backdated commits for a realistic sequence of events.
• Backdated Merge Commits: Merge a feature branch into the main branch with a backdated merge commit. GitLegends performs a no-fast-forward merge locally and creates a merge commit carrying the specified date (in the past), then pushes it. GitHub will recognize the merge commit and mark the pull request as merged.
• One-Command Workflow (commit-all): Use a single command to automate the full cycle: create a backdated commit on a new branch, push it, open a PR, (optionally auto-approve and comment), then merge with a backdated commit and clean up the branch. This is a quick way to simulate the entire feature development workflow in one go.
• Dry Run Mode: A global dry-run option (--dry-run) allows you to preview the Git and GitHub actions without actually executing them. This is useful for testing your configuration or commands before making any real changes.
• Configurable Defaults: You can configure default settings (like default branch name, GitHub organization/user, repository visibility, etc.) through a YAML config file or environment variables. This makes it easy to set up once and reuse for multiple simulation runs.
• Minimal Dependencies: GitLegends primarily relies on your local Git installation and the GitHub CLI. The Python package itself has few dependencies (aside from PyYAML for config files), making it lightweight and easy to add to your toolkit.

How GitLegends Works

Under the hood, GitLegends uses environment variables and Git's inherent features to manipulate commit history dates:

• Backdating Commits: Git allows overriding the author and committer dates by setting the environment variables GIT_AUTHOR_DATE and GIT_COMMITTER_DATE before making a commit. GitLegends takes the date you provide (in various acceptable formats) and converts it to an ISO8601 UTC timestamp, then sets these environment variables for the duration of the commit. The result is a commit in your repository's history that shows the specified past date.
• Backdating Merge Commits: Similar to regular commits, merge commits are created by first merging without finishing (git merge --no-ff --no-commit), then setting the desired date and committing. The merge commit message can reference the pull request number (if one was used) to mimic a real GitHub merge. Once pushed, GitHub will link it to the PR and mark it as merged, with the merge commit's date reflecting your chosen past time.
• Pull Requests via GitHub CLI: The tool uses the GitHub CLI (gh) under the hood for operations like creating repositories, opening pull requests, adding PR comments, and reviews, etc. It ensures that branches are pushed to GitHub before opening PRs to avoid any "no commits" errors. While PR metadata on GitHub (creation time, etc.) can't be backdated, these steps integrate the backdated commits into the normal GitHub workflow.
• Local-First Approach: All commit and merge operations happen locally in your Git repository with controlled dates, then the history is pushed to GitHub. This approach means you have a chance to verify things (especially with dry-run) before they appear on GitHub.

GitLegends effectively scripts Git and GitHub CLI calls in sequence to automate a scenario. For example, creating a feature might involve: making sure you have a repository and base branch, creating a new branch, making a commit with an old date, pushing the branch, opening a PR, and then merging it with a dated commit. Each of these steps can be done with individual commands or combined in the one-shot command. The tool manages potential pitfalls (like ensuring branches exist or are pushed, or closing PRs after merge) so that the process is smooth.

Use Cases

• Demo Repositories: Create a repository for a portfolio or demo that shows steady progress over time (even if you built it in one day). Impress others with a realistic commit timeline and PR history.
• Education and Training: Simulate the software development lifecycle (feature branches, code reviews, merges) for training junior developers or demonstrating Git/GitHub flows in a workshop, all with controlled timing.
• Project Reconstruction: If you want to reconstruct a project's commit history from scratch (for example, after doing work in a single private repo, you want to open source it with a richer history), you can use GitLegends to replay the history with appropriate timestamps.
• Timeline Planning: Plan out a roadmap or timeline for a project in advance. You could outline dates for features and releases, then use GitLegends to create placeholder commits and merges on those dates. This can even aid in visualization of a project timeline using Git's history.

GitLegends makes it easy to craft a narrative in your Git history. With the overview covered, you can proceed to installing GitLegends and trying it out with a quickstart example.