| Name | gh-star-timeline JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | Command-line tool to keep track of historic stars on github. Machine-useable output. |
| upload_time | 2025-04-22 23:13:25 |
| maintainer | None |
| docs_url | None |
| author | @readwithai |
| requires_python | None |
| license | GPLv3 |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Github star timeline cli
**@readwithai** - [X](https://x.com/readwithai) - [blog](https://readwithai.substack.com/) - [machine-aided reading](https://www.reddit.com/r/machineAidedReading/)
`gh-star-timeline` maintains a timeline of the number of stars that a repository has over time.
Basic statistical aggregates can be queried offline
## Alternatives and prior work
There are many open source projects on github which do similar things.
[starcount](https://github.com/starkblaze01/Star-Count) and [gh-stars](https://github.com/jonschlinkert/gh-stars) fetch the number of stars for all repositories a user has, but at a specific point in time. I have reimplemented much of this functionality here because I wanted to maintain a timeline. One could alternatively wrap this tool.
[star history](https://www.star-history.com/) can produce plots (but only plots) of the historic number of starts for a repository and is [open source](https://github.com/star-history/star-history). I believe this uses the `stargazers` api which can provide the time that a repository was starred (See [this snippet](https://gist.github.com/jasonrudolph/5abee158b42b99a3990a))
This sort of timeline can be regenerated (up-to stars being removed) from ghis snippet.
I have a similar project, [gh-views](https://github.com/talwrii/gh-views), which fetches the number of views and clones for repository.
## Installation
You can install `gh-star-timeline` using [pipx](https://github.com/pypa/pipx):
```
pipx install gh-star-timeline
```
You just also install the github command-line tool [gh](https://github.com/cli/cli) and log in to github with `gh auth login`.
# Usage
To fetch the total number of stars for a repository you can run e.g.
```
gh-star-timeline talwrii/ffmpeg-cookbook
```
To get the number of stars for each repo (analogous to [starcount](https://github.com/starkblaze01/Star-Count). This is can be a little slow. It should be faster on later runs.
```
gh-star-timeline --user talwrii
```
You can use the `-n` option to use fetched data.
If you want the total number of stars for all your repositories, you can run:
```
gh-star-timeline --user talwrii -n --total
```
To get the history of all stars added (or removed - while you where using `gh-star-timeline`). You can use:
```
gh-star-timeline talwrii/curlfire --stars -n
```
To get a timeline of stars counts over time you can use `--timeseries`
```
gh-star-timeline talwrii/curlfire -n --timeseries
```
It would be relative easy to plot this.
You can get a timeseries of the total number of stars across all your repos with:
```
gh-star-timeline talwrii/curlfire -n --timeseries -T
```
## Periodically fetching
You can fetch a complete history of star counts (apart from removed stars) at any time by running *without* the `-n` option. You may like to run periodically to keep your local stats up-to-date and detect people removing stars.
This could be done with a [systemd timer](https://www.freedesktop.org/software/systemd/man/latest/systemd.timer.html) or [cron job](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/) or a variety o other methods
## Backing up data
Data is stored in `~/.local/state/gh-star-timeline`. You may wish to periodically back up this data.
## Caveats
`gh-star-timeline` was written and tested on Linux. It will probably work on Mac without any alteration. The paths may need to be adapted for windows - this should be an easy change if you are familiar with the Python programming language and I will accept and quickly merge and pull requests for windows support.
## Support
If you find this project useful you could pay me money ($3 maybe) on my [ko-fi](https://ko-fi.com/c/965d8a3fca). This will incentivize me to respond to issues with this repo and work on [similar command-line tools](https://readwithai.substack.com/p/my-productivity-tools)
You could also look at a similar tool I made to track views and clones of a github repo: [gh-views](https://github.com/talwrii/gh-views). Or read some of the things that I have written surrounding note-taking and reading. Perhaps this [review of note-taking in Obsidian](https://readwithai.substack.com/p/note-taking-with-obsidian-much-of).
## About me
I am **@readwithai** I make tools for reading, research and agency, sometimes using [Obsidian](https://readwithai.substack.com/p/what-exactly-is-obsidian).
You can follow me on [X](https://x.com/readwithai) where I write about many things - including productivity tools like this. Or you can read my [blog](https://readwithai.substack.com/) where I write more around reading and research
Raw data
{
"_id": null,
"home_page": null,
"name": "gh-star-timeline",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "@readwithai",
"author_email": "talwrii@gmail.co",
"download_url": "https://files.pythonhosted.org/packages/ae/17/a4ffc8df50bd35efbd5ffe2dcfe0661be38eade37968a94b65bb0ee494e7/gh-star-timeline-1.1.0.tar.gz",
"platform": null,
"description": "# Github star timeline cli\n**@readwithai** - [X](https://x.com/readwithai) - [blog](https://readwithai.substack.com/) - [machine-aided reading](https://www.reddit.com/r/machineAidedReading/)\n\n`gh-star-timeline` maintains a timeline of the number of stars that a repository has over time.\n\nBasic statistical aggregates can be queried offline\n\n## Alternatives and prior work\nThere are many open source projects on github which do similar things.\n\n[starcount](https://github.com/starkblaze01/Star-Count) and [gh-stars](https://github.com/jonschlinkert/gh-stars) fetch the number of stars for all repositories a user has, but at a specific point in time. I have reimplemented much of this functionality here because I wanted to maintain a timeline. One could alternatively wrap this tool.\n\n[star history](https://www.star-history.com/) can produce plots (but only plots) of the historic number of starts for a repository and is [open source](https://github.com/star-history/star-history). I believe this uses the `stargazers` api which can provide the time that a repository was starred (See [this snippet](https://gist.github.com/jasonrudolph/5abee158b42b99a3990a))\n\nThis sort of timeline can be regenerated (up-to stars being removed) from ghis snippet.\n\nI have a similar project, [gh-views](https://github.com/talwrii/gh-views), which fetches the number of views and clones for repository.\n\n## Installation\nYou can install `gh-star-timeline` using [pipx](https://github.com/pypa/pipx):\n\n```\npipx install gh-star-timeline\n```\n\nYou just also install the github command-line tool [gh](https://github.com/cli/cli) and log in to github with `gh auth login`.\n\n# Usage\nTo fetch the total number of stars for a repository you can run e.g.\n```\ngh-star-timeline talwrii/ffmpeg-cookbook\n```\n\nTo get the number of stars for each repo (analogous to [starcount](https://github.com/starkblaze01/Star-Count). This is can be a little slow. It should be faster on later runs.\n\n```\ngh-star-timeline --user talwrii\n```\n\nYou can use the `-n` option to use fetched data.\n\nIf you want the total number of stars for all your repositories, you can run:\n\n```\ngh-star-timeline --user talwrii -n --total\n```\n\nTo get the history of all stars added (or removed - while you where using `gh-star-timeline`). You can use:\n```\ngh-star-timeline talwrii/curlfire --stars -n\n```\n\nTo get a timeline of stars counts over time you can use `--timeseries`\n```\ngh-star-timeline talwrii/curlfire -n --timeseries\n```\nIt would be relative easy to plot this.\n\nYou can get a timeseries of the total number of stars across all your repos with:\n```\ngh-star-timeline talwrii/curlfire -n --timeseries -T\n```\n\n## Periodically fetching\nYou can fetch a complete history of star counts (apart from removed stars) at any time by running *without* the `-n` option. You may like to run periodically to keep your local stats up-to-date and detect people removing stars.\n\nThis could be done with a [systemd timer](https://www.freedesktop.org/software/systemd/man/latest/systemd.timer.html) or [cron job](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/) or a variety o other methods\n\n## Backing up data\nData is stored in `~/.local/state/gh-star-timeline`. You may wish to periodically back up this data.\n\n## Caveats\n`gh-star-timeline` was written and tested on Linux. It will probably work on Mac without any alteration. The paths may need to be adapted for windows - this should be an easy change if you are familiar with the Python programming language and I will accept and quickly merge and pull requests for windows support.\n\n## Support\nIf you find this project useful you could pay me money ($3 maybe) on my [ko-fi](https://ko-fi.com/c/965d8a3fca). This will incentivize me to respond to issues with this repo and work on [similar command-line tools](https://readwithai.substack.com/p/my-productivity-tools)\n\nYou could also look at a similar tool I made to track views and clones of a github repo: [gh-views](https://github.com/talwrii/gh-views). Or read some of the things that I have written surrounding note-taking and reading. Perhaps this [review of note-taking in Obsidian](https://readwithai.substack.com/p/note-taking-with-obsidian-much-of).\n\n## About me\nI am **@readwithai** I make tools for reading, research and agency, sometimes using [Obsidian](https://readwithai.substack.com/p/what-exactly-is-obsidian).\n\nYou can follow me on [X](https://x.com/readwithai) where I write about many things - including productivity tools like this. Or you can read my [blog](https://readwithai.substack.com/) where I write more around reading and research\n\n\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Command-line tool to keep track of historic stars on github. Machine-useable output.",
"version": "1.1.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ae17a4ffc8df50bd35efbd5ffe2dcfe0661be38eade37968a94b65bb0ee494e7",
"md5": "90275e3c36b803545c4d1894f9e8ae60",
"sha256": "ed51b7e9c1594eb7d97bc083aeae5cf1ab4e95dad2bc8acb45a39ee1eb9c3529"
},
"downloads": -1,
"filename": "gh-star-timeline-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "90275e3c36b803545c4d1894f9e8ae60",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6140,
"upload_time": "2025-04-22T23:13:25",
"upload_time_iso_8601": "2025-04-22T23:13:25.631194Z",
"url": "https://files.pythonhosted.org/packages/ae/17/a4ffc8df50bd35efbd5ffe2dcfe0661be38eade37968a94b65bb0ee494e7/gh-star-timeline-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-04-22 23:13:25",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "gh-star-timeline"
}
