documentation

everything you need to know about shōmei

basic usage

1. install shōmei

pip install shomei

2. run from your work repo

cd ~/work/my-project
shomei

3. follow the prompts

shōmei will ask you for:

  • your personal GitHub username
  • what to name the mirror repository
  • your GitHub personal access token

4. wait for it to finish

shōmei will scan your commits, create a repo on your personal GitHub, and mirror all your commit dates. this usually takes a few minutes depending on how many commits you have.

5. check your contribution graph

go to your GitHub profile and refresh. your contribution graph should update within a few minutes.

command-line options

--dry-run

preview what would happen without actually creating anything: 

shomei --dry-run

--private

create a private mirror repository instead of public: 

shomei --private

--version

check which version of shōmei you have installed: 

shomei --version

--help

show help message: 

shomei --help

github token setup

you need a GitHub personal access token with repo permissions. here's how to get one:

  1. go to GitHub Settings → Developer settings → Personal access tokens
  2. click "Generate new token (classic)"
  3. give it a name like "shomei"
  4. check the repo checkbox (full control of private repositories)
  5. click "Generate token"
  6. copy the token (GitHub only shows it once!)
  7. save it somewhere safe (like a password manager)
  8. use it when shomei asks for your token

important: never share your token publicly. treat it like a password. if you accidentally expose it, revoke it immediately and create a new one.

how it works

1. scan commits

runs git log --author your@email.com to find all your commits in the current repo.

2. extract dates

pulls out just the commit dates. no code, no messages, no file names. just timestamps.

3. create repo

uses GitHub's API to create a new repository on your personal account.

4. mirror commits

creates empty commits with your dates via GitHub's API. no code ever leaves your machine.

5. generate README

creates a README for your mirrored repo with stats, badges, and links back to shōmei.

6. update graph

GitHub automatically updates your contribution graph to show the new commits.

7. done!

your contribution graph now reflects your real work. recruiters can see you're active.

frequently asked questions

is this safe?

yes. shōmei only sends commit dates to GitHub's API. no code, no commit messages (beyond "ci(shōmei): sync work contribution"), no file names. your company's IP never touches the internet.

will this get me in trouble?

we're not lawyers, but: you're not exposing any proprietary code or information. just timestamps. that said, check your company's policies if you're worried.

does this work with private work repos?

yes! shōmei reads your local git log. it doesn't matter if the work repo is public or private. it only reads commit metadata from your local clone.

can I make the mirror repo private?

yep! use the --private flag: shomei --private

what if I want to delete everything later?

just delete the mirror repo from GitHub. your original work repo is never touched or modified.

can I customize the commit messages?

not yet, but that's a great idea! if you want this feature, open an issue or send a PR.

why not just change the git config on my work repos?

because then you'd be committing to company repos with your personal email, which might break things or violate policies. shōmei keeps everything separate and safe.

does it work with GitLab/Bitbucket/etc?

not yet, only GitHub for now. but adding support for other platforms would be awesome! want to contribute? check out the contributing guide.

can I run this on multiple repos?

yes! just cd into each repo and run shomei. you'll create a separate mirror repo for each one.

what if I have thousands of commits?

shōmei handles this gracefully. it adds delays between API calls to respect GitHub's rate limits. it might take a while, but it'll work.

I'm getting API errors, what do I do?

check that your GitHub token has repo permissions and hasn't expired. if it's a rate limit issue, wait a few minutes and try again. if the problem persists, open an issue.

want to contribute?

we'd love your help! whether it's:

  • reporting bugs
  • suggesting features
  • improving docs
  • writing code
  • or just starring the repo ⭐

check out the contributing guide to get started.