Quickstart Guide

This quickstart will walk you through a typical GitLegends workflow: creating a new repository with an initial backdated commit, adding a feature branch with backdated commits, and merging it via a pull request with a backdated merge commit. By the end, you’ll have a repository on GitHub that looks as if it had commits and a merge that happened in the past.

1. Create a New Repository with a Backdated Initial Commit

First, use the create-repo command to initialize a new repository:

legends create-repo my-backdated-repo \
  --owner your-github-username \
  --date "2024-12-01T12:00:00" \
  --private \
  --description "Backdated repo demo"

What this does:

• Creates a new local directory named my-backdated-repo and initializes it as a Git repository.
• Generates a README file (with the given description) and makes the initial commit. The commit’s date is set to Dec 1, 2024, 12:00:00 UTC (as provided in the --date).
• Sets the default branch name (if not specified, it uses the default from config, e.g., “main”).
• Uses the GitHub CLI to create a remote repository under your specified --owner (this could be your username or an organization) with name “my-backdated-repo”, visibility private (because of --private flag), and pushes the initial commit to that remote.
• Essentially, your GitHub account will now have a repository my-backdated-repo with one commit in its history from 2024.

2. Create a Feature Branch (with a historical "birth" commit)

Next, simulate starting a new feature branch sometime after the initial commit date. Use create-branch to create a branch with a backdated empty commit:

cd my-backdated-repo
legends create-branch feature-login \
  --base main \
  --date "2025-02-01T09:00:00" \
  --message "chore(feature-login): branch birth @ 2025-02-01T09:00:00" \
  --push

What this does:

• Checks out the base branch (here main) and then creates a new branch called feature-login from it.
• Creates an empty commit on feature-login with the message provided (or a default message if not given) and sets its timestamp to Feb 1, 2025, 09:00:00.
• The --push flag then pushes the new branch to the remote (origin). This means on GitHub, the branch feature-login now exists, and it appears as if it was created on Feb 1, 2025 (the commit date).
• This empty commit effectively marks the "birth" of the feature branch at that date.

At this point, your repository’s commit history has:

• main branch: an initial commit on Dec 1, 2024.
• feature-login branch: one commit (with no changes) on Feb 1, 2025.

3. Make Backdated Commits on the Feature Branch

Now, add some feature development commits to the feature-login branch, backdated to when you "would have" developed the feature:

# On feature-login branch, add the backend implementation (dated Feb 10, 2025)
legends commit --branch feature-login \
  --date "2025-02-10T15:00:00" \
  --message "feat(login): implement login backend" \
  --add-all --push

# Still on feature-login, add another commit for frontend (dated Feb 15, 2025)
legends commit --branch feature-login \
  --date "2025-02-15T10:30:00" \
  --message "feat(login): add frontend for login" \
  --add-all --push

Here’s what each commit command is doing:

• It checks out the specified branch (feature-login) if not already on it.
• If you pass --add-all, it stages all changes (running git add -A). In this example, you would have made changes to your code (for the login feature) before running the command. The --add-all conveniently stages them.
• It creates a commit with the provided message and date. The --date ensures the commit’s timestamp is set (Feb 10 and Feb 15, 2025 in the examples above).
• The --push flag pushes the commit to GitHub immediately. This updates the remote branch.

After these two commands, the feature-login branch will have two actual commits: one on Feb 10, 2025 and one on Feb 15, 2025, with the respective messages. These could contain code for the login feature (backend and frontend).

4. Open a Pull Request for the Feature

With the feature branch ready (and containing backdated commits), the next step is to open a Pull Request (PR) on GitHub to merge feature-login into main:

legends open-pr --branch feature-login --base main \
  --title "Feature: User Login" \
  --body "Adds backend and UI for user login."

What this does:

• Pushes the branch to GitHub if it wasn’t already pushed (in our case, we have been pushing along the way).
• Uses the GitHub CLI to open a new PR, comparing feature-login (head) into main (base).
• Sets the PR title and body as given. (If you omit --title or --body, defaults are used; by default, the branch name might be used as the title if none provided.)
• The PR will appear on GitHub with the two commits we made. The PR’s timestamps (created time) will be the current time (cannot be backdated), but the commits inside show Feb 10 and Feb 15, 2025 dates.

At this point, you have a pull request open, as if you just submitted the feature for review. You could even navigate to it on GitHub to see that everything looks right (commits, diffs, etc., all present).
(Optional: You could use gh pr view --web to open it in a browser, or just find it on GitHub.)

5. Merge the Pull Request with a Backdated Merge Commit

Finally, simulate merging the PR after some review period. We’ll merge feature-login into main with a merge commit dated in the past (e.g., Mar 1, 2025):

legends merge-pr --branch feature-login --base main \
  --date "2025-03-01T17:00:00" --delete-branch

What this does:

• Checks out the base branch (main) and makes sure it’s up to date (pulls the latest from origin).
• Merges the feature-login branch into main without immediately committing (using a no-fast-forward, no-commit merge). This brings in the changes from the feature branch.
• Creates a merge commit with the message “Merge pull request #<number> from feature-login” (unless you provided a custom --message). This commit’s timestamp is set to Mar 1, 2025 per the --date. The author of the merge commit will be set to your name (and committer possibly as your GitHub login, depending on config).
• Pushes the main branch to GitHub, so the merge commit appears on the remote repository.
• Because we used --delete-branch, GitLegends will then attempt to close the PR on GitHub and delete the remote branch. Since it knows the PR number (from earlier or by checking), it will close the PR via gh pr close. GitHub will mark the PR as merged (because the exact merge commit is now on the main branch) and will remove the branch from the remote.
• Locally, your feature-login branch still exists, but you can delete it if you wish. On GitHub, that branch is gone (to keep things tidy).

Now your repository’s main branch has a new merge commit dated March 1, 2025, which merged in the feature. The commit history on main will show: Initial commit (Dec 1, 2024) -> Merge commit (Mar 1, 2025). And if you look at the network or commit graph, the feature-login branch diverged and merged back.

You have successfully created a realistic historical timeline:

• The project started in Dec 2024.
• A feature branch was started on Feb 1, 2025, with work done on Feb 10 and 15, 2025.
• That feature was merged on Mar 1, 2025 via a PR.

Anyone viewing the repository’s commits or branches will see this history. The only give-away of the simulation is that the PR itself shows it was opened/merged at the current date (because GitHub doesn’t allow changing those), but the commits and merge commit show the intended past dates.

6. One-Shot Automation (Alternative)

GitLegends provides a single command that can do steps 3–5 in one go: commit-all. For example, the above process for feature-login could be done as:

# This single command creates a commit, opens a PR, and merges it with given dates
legends commit-all \
  --base main \
  --branch feature-login \
  --commit-date "2025-02-10T15:00:00" \
  --message "feat(login): implement login and UI" \
  --pr-title "Feature: User Login" \
  --pr-body "Adds backend and UI." \
  --merge-date "2025-03-01T17:00:00" \
  --delete-branch

This will:

• Create feature-login branch (if it doesn’t exist) from main.
• Make one commit on it with date Feb 10, 2025 (you could still use --touch or --allow-empty if needed to ensure there’s something to commit).
• Push the branch and open a PR with the given title/body.
• Immediately merge that PR with a merge commit dated Mar 1, 2025, then delete the branch.

Using commit-all is powerful for quickly generating a feature’s entire lifecycle. However, it’s often clearer to start with the step-by-step approach (as we did) to understand each piece. You can choose the method that suits your needs.