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

shōmei works with both classic and fine-grained personal access tokens. choose the option that works best for you:

option 1: classic token (easier, recommended for personal use)

  1. go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. click "Generate new token (classic)"
  3. give it a name like "shomei"
  4. check the repo checkbox (this gives full repository access)
  5. set an expiration date (or "No expiration" if you prefer)
  6. generate and copy the token
  7. use it when shomei asks for it

option 2: fine-grained token (more secure, better control)

fine-grained tokens offer more security through granular permissions:

  1. go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
  2. click "Generate new token"
  3. give it a name like "shomei"
  4. set an expiration date
  5. repository access:
    • select "All repositories" (if you want to mirror any repo)
    • OR select "Public Repositories (read and write)" (if you only mirror public repos)
    • important: do NOT select "Only select repositories" unless you manually create the repo first (see option 3)
  6. permissions → account permissions:
    • scroll down to find "Administration"
    • set it to "Read and write"
    • this permission allows shomei to create repositories on your account
  7. generate and copy the token
  8. use it when shomei asks for it

option 3: manual repo + restricted token (most secure)

for maximum security, you can manually create the mirror repo first and use a token with access to ONLY that repo:

1. create the mirror repo manually:

  • go to github.com/new
  • create a repo (e.g., "my-work-mirror")
  • make it public or private (your choice)

2. create a fine-grained token with minimal permissions:

  • go to GitHub Settings → Fine-grained tokens
  • click "Generate new token"
  • give it a name like "shomei-restricted"
  • set an expiration date
  • repository access: select "Only select repositories" → choose your mirror repo
  • permissions → repository permissions: set "Contents" to "Read and write"
  • that's it! no Administration permission needed
  • generate and copy the token

3. run shomei:

  • when prompted for the repo name, use the SAME name as your manually-created repo
  • shomei will detect the existing repo and add commits to it
  • your token only has access to that one repo - nothing else!

pro tip: save the token somewhere safe (like a password manager). GitHub only shows it once!

important: don't manually create the mirror repository - shomei creates it automatically for you. if you create it manually, you may encounter permission errors.

security: 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.

I'm getting "Resource not accessible by personal access token" error. What's wrong?

this happens when your GitHub token doesn't have the right permissions. you have two options:

  • option 1: use a token with broader permissions (Administration: Read and write for fine-grained, or repo scope for classic)
  • option 2 (more secure): manually create the mirror repo first, then use a fine-grained token with "Only select repositories" access to just that repo. shomei will detect the existing repo automatically!

see the github token setup section above for detailed instructions on both approaches.

does shomei support fine-grained personal access tokens?

yes! shomei works with both classic and fine-grained tokens. fine-grained tokens are more secure and give you better control over permissions. see the token setup guide above for instructions on configuring both types.

can I use an existing repository instead of creating a new one?

absolutely! just create the repo manually on GitHub first, then run shomei with the same repo name. shomei will detect the existing repo and add commits to it. this is perfect if you want to use a fine-grained token with "Only select repositories" access - no Administration permission needed, just Contents: Read and write!

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.