Examples & Workflows

To further illustrate GitLegends’ capabilities, this section presents a couple of examples and scenarios. These examples build on the basic quickstart and show how you can simulate more complex project histories.

Example 1: Multi-Feature Development Timeline

Suppose you want to create a repository that looks like an entire quarter’s worth of development work. You have an initial release, two feature developments (Feature A and Feature B), and a hotfix, each on separate branches and merged in sequence. Here’s how you could do it with GitLegends:

# 1. Initialize a new repo with an initial commit in the past (e.g., last December)
legends create-repo quarterly-demo \
  --date "2024-12-01T10:00:00" \
  --private \
  --description "Demo project with quarterly timeline"

# 2. Feature A development (branch start in Feb, two commits, merge in late Feb)
legends create-branch feature-a --date "2025-02-01T09:00:00" --push
legends commit --branch feature-a --date "2025-02-05T14:00:00" \
  --message "feat(feature-a): core implementation" --allow-empty --push
legends commit --branch feature-a --date "2025-02-10T16:30:00" \
  --message "feat(feature-a): add enhancements" --allow-empty --push
legends open-pr --branch feature-a --title "Feature A"
legends merge-pr --branch feature-a --date "2025-02-20T17:00:00" --delete-branch

# 3. Feature B development (one-shot using commit-all in March)
legends commit-all --branch feature-b --base main \
  --commit-date "2025-03-10T11:00:00" \
  --message "feat(feature-b): initial implementation" \
  --pr-title "Feature B" \
  --merge-date "2025-03-18T18:00:00" \
  --delete-branch

# 4. Hotfix in April (simulate a quick bug fix on main)
legends commit-all --branch hotfix-timeout --base main \
  --commit-date "2025-04-02T09:00:00" \
  --message "fix: resolve token refresh timeout issue" \
  --pr-title "Hotfix: Token Refresh Timeout" \
  --merge-date "2025-04-03T13:00:00" \
  --delete-branch

Let’s break down what happens here:

• The repo quarterly-demo is created with an initial commit on Dec 1, 2024.
• Feature A: A branch is born on Feb 1, 2025. We then commit twice on that branch (Feb 5 and Feb 10). We open a PR for Feature A and merge it on Feb 20, 2025. (We used --allow-empty for commits just to simulate changes without actual file content, but in practice you’d be adding real changes).
• Feature B: Instead of multiple manual steps, we use commit-all to simulate a feature in March. It creates feature-b branch, commits on Mar 10, opens PR, merges on Mar 18.
• Hotfix: We use commit-all again to simulate a quick hotfix branch in early April, merged by April 3.

When this is done, the repository’s history will look like:

• Initial commit (Dec 2024)
• Merge of Feature A (Feb 20, 2025) into main – with two commits on feature-a in early Feb.
• Merge of Feature B (Mar 18, 2025) into main – with one commit on feature-b on Mar 10.
• Merge of Hotfix (Apr 3, 2025) into main – with one fix commit on Apr 2.

The GitHub contribution graph for the committer email used would show activity on those dates. The repository’s commit log would have entries in December, February, March, April corresponding to these actions.

This is a powerful demonstration of how a repository can be made to look active over a period of time. It could be useful for generating test data, demonstrations, or backfilling a history.

Example 2: Backdating an Existing Repository’s History

Another scenario: you have an existing repository that you created recently, but you want to spread its commits out over the past year. While GitLegends is primarily designed for new orchestrated commits, you could use it on an existing repo by carefully resetting and replaying history. This is an advanced use case and caution is advised (rewriting history in a published repo can confuse collaborators).

High-level approach:

• Use git checkout --orphan to create a new orphan branch (no history).
• Use GitLegends commands (commit) to add commits with desired dates in order.
• Force-push this new branch over the old main branch on GitHub.

For example, say you have a project with 5 major changes, and you want them to appear as if they were done one per month over the last 5 months:

• You’d prepare 5 sets of changes (or you can commit the existing state 5 times).
• Starting from an empty branch, run legends commit with dates for each of those months.
• After creating this chain of commits, you’d force push to the GitHub repo.

Example 3: Automated Timeline from Spec (Advanced)

If you have a specification of a project timeline (e.g., in a file or script), you could integrate with GitLegends to automate it. For instance, you might have a YAML or JSON file with entries for each planned commit or feature branch (with dates and messages). While GitLegends doesn’t directly consume such a file to run multiple steps (it operates one command at a time), you can write a short Python or shell script to read your timeline file and invoke GitLegends commands accordingly.

Consider a YAML like:

- action: create-repo
  name: timeline-demo
  date: 2024-01-01 10:00:00
  description: "Timeline demo"

- action: create-branch
  branch: feature-x
  base: main
  date: 2024-02-01 09:00:00

- action: commit
  branch: feature-x
  date: 2024-02-05 13:00:00
  message: "Implement X"

- action: open-pr
  branch: feature-x
  base: main
  title: "Feature X"

- action: merge-pr
  branch: feature-x
  date: 2024-02-10 17:00:00

This is a conceptual example. You could iterate through such a list and execute the corresponding legends commands. In fact, if you are comfortable with Python, you could import the legends package and call the underlying functions to have finer control (bypassing CLI parsing), but using the CLI in a script works just as well.

The above approach is for power-users who want to design an entire history in a declarative way and then realize it. This is not out-of-the-box functionality of GitLegends, but the tool is flexible enough to be scripted in this manner.