FAQ & Troubleshooting

Q: Will backdated commits count towards my GitHub contributions on those past dates?

A: Yes. GitHub’s contribution graph is based on the timestamps of commits (and whether those commits are associated with your account via email). If you backdate commits to last year, those dates will show contributions. This means you should use this tool responsibly – for example, don’t falsify contributions in a way that violates any terms of service. But for legitimate purposes (recovering history, demo content), it’s a useful feature.

Q: Can I change the dates of pull request events (opening, merging) on GitHub?

A: No. GitHub records the actual time a PR is opened or merged (and when reviews/comments are made). GitLegends cannot alter those timestamps because they are set server-side by GitHub. The tool focuses on commit dates and merge commit dates, which are part of the Git history and under your control. When you use merge-pr, the merge commit in Git will have the backdated time, but the PR page will say “Merged on [today’s date]” because that reflects the GitHub action time.

Q: Do I ever need to use force-push with GitLegends?

A: In normal workflows, no, you shouldn’t need --force. GitLegends builds history on top of what’s there. You create new commits and push new branches or merges. Force-pushing would only be needed if you, for example, wanted to rewrite an existing branch’s history with new dates or changes. In such cases, that’s outside the typical use of GitLegends and more of a manual Git task (though you could use GitLegends to help craft the rewritten commits). Always be cautious with force-pushing, especially on shared or public repositories.

Q: What date formats can I use for the --date option?

A: GitLegends is flexible in parsing dates. You can use:

• YYYY-MM-DD (dates only; the time will default to 00:00:00).
• YYYY-MM-DD HH:MM or YYYY-MM-DD HH:MM:SS (in 24-hour format; seconds optional).
• ISO 8601 format like YYYY-MM-DDTHH:MM:SSZ (UTC) or with a timezone offset (e.g., 2025-03-01T17:00:00+02:00). If you include a Z or offset, it will interpret accordingly.

If you provide no timezone (e.g., 2025-03-01 17:00:00), it assumes that’s your local time and will convert it to UTC internally (because Git commit objects store times in UTC).

Make sure to quote the date in the command (especially if it contains spaces) to avoid shell parsing issues.

Q: The tool created commits with the wrong author name/email. How do I fix this?

A: GitLegends tries to pick up your name and email from the GitHub CLI (gh) identity or your environment. If it’s not what you expect, you can explicitly set the environment variables GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL (and the committer variants) before running the commands, or use --author-name/--author-email for the create-repo initial commit. Also, ensure your global git config has the correct user name and email, as a fallback. If you already made commits with the wrong info, you’d have to rewrite those commits (which is an advanced Git task).

Q: I ran merge-pr but the PR on GitHub didn’t close automatically.

A: GitLegends attempts to close the PR via the GitHub CLI after pushing the merge commit. There are a few reasons it might not close:

• If the PR was already closed or merged (perhaps you merged manually), GitLegends may skip or the CLI might not find an open PR.
• If the GH CLI failed (network issue, or lacking permissions), the command to close might not have executed. In this case, you can manually run gh pr close <number> --delete-branch.
• If for some reason GitHub didn’t recognize the merge (like if the commit message didn’t have the PR number and auto-close keyword, though GitHub typically keys off the commit relationships, not just message), you might need to close manually. Ensure you used --no-ff merge as the tool does by default, otherwise GitHub might not see a merge commit.

In most cases, if you use merge-pr as provided, the PR should be marked merged by GitHub because the pushed merge commit will be associated to it. GitLegends includes the PR number in the merge commit if it knows it, which helps GitHub link them.

Q: I got an error "Required tool not found: 'git'" or "'gh'".

A: This means Git or GitHub CLI isn’t available in the PATH where you ran GitLegends. Make sure you can run git and gh in that environment. Install them or adjust your PATH, then try again.

Q: The command fails with authentication errors when creating a repo or PR.

A: Make sure your GitHub CLI is authenticated (gh auth login) or that you have a valid token in the environment. By default, gh will use the credentials from gh auth login. If you prefer using a token directly, set GITHUB_TOKEN (or GH_TOKEN). Also ensure the token has appropriate scopes (repo access for private repos, etc.).

Q: I see an error about PyYAML not installed when using --config.

A: The YAML support requires PyYAML. If you installed GitLegends via pip, this should have been included. But if not, install it with pip install PyYAML. Alternatively, you can avoid using YAML and stick to env vars or CLI flags.

Q: The legends command is not found after installation.

A: If you installed via pip but it’s not found, it could be a PATH issue. Make sure the installation’s scripts directory is in your PATH. For example, if you installed in a virtualenv, activate that environment. If you installed --user, ensure ~/.local/bin (or the equivalent on your OS) is in PATH.