diff --git a/README.md b/README.md index 469338e..4639b19 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,90 @@ # gh-starred-to-opml -Generates OPML 2.0 files to track the syndication of Releases from your favorite Github repositories. In their whole or by listings. \ No newline at end of file +Generates OPML 2.0 files to track the syndication of Releases from your favorite Github repositories. In their whole or by listings. + +---- + + +## Introduction + +Each repository's Releases page on Github has a link to an atom file. + +This **syndication feeds** allows, among other things : + - to monitor the appearance of new releases, + - without having to bother with notifications, + - to monitor the disappearance of a repository. + +Moreover with the recent feature of **[starred repositories lists](https://github.blog/changelog/2021-12-09-lists-are-now-available-as-a-public-beta/)**, you can choose to **follow only some personal categories** of releases. + +- The **1st issue** lies in the fact tha **Github's interface does not provide** any feature to **export** thoses atom file in bulk. + + Github's API does provide an [endpoint](https://docs.github.com/en/rest/activity/starring?apiVersion=2022-11-28#list-repositories-starred-by-a-user) to fetch all the repositories starred by an user, it's easy to generate the atom list from here. + +- But, a **2nd issue** is that this **[API does not yet provide](https://github.com/community/community/discussions/8293)** an endpoint to **filter the starred repositories by a List** created by the user. + +**gh-starred-to-opml** is a script that will fetch these informations for you and generate a file that can be imported in most Feed Reader applications, like [Miniflux](https://github.com/miniflux/v2). + + +## Requirements + +- Run with bash 5.+ +- curl (sudo apt install curl) +- [jq](https://github.com/stedolan/jq/) (sudo apt install jq) +- [pup](https://github.com/ericchiang/pup) (go install github.com/ericchiang/pup@latest) + + +## Usage + +```bash +./gh-starred-to-opml.sh -h +Generate an OPML 2.0 file to follow releases of starred repositories on Github +Default to all starred repos of the user, or a specific list with [-l list]. + +Syntax: ./gh-starred-to-opml.sh [-h] -u user [-l listname] [-d date] [-o filename] [-n filename] +options: +-h Print this Help +-u string required: Github username +-l string optional: Github Stars List (url shortname) +-d string optional: ISO8601 date to filter out starred before (YYYY-mm-ddTHH:MM:SSZ) +-o string.opml optional: destination opml filename +-n string.opml Use a previous file to generate updates, + it does not require any other option, + but it uses starred_at dates, not starred in a list. +``` + +The resulting file can be imported in a Feed Reader. + - The first `` will provide the category's name. + - `` & `` respresent the oldest & most recent dates where repositories in the list where starred. It can help for updates. + +## Example + +Cropped OPML extract from my Favorites list: + +```xml + + + + gh_starred_tkapias_favorites.opml + Fri, 06 Sep 2019 19:35:09 GMT + Sun, 12 Feb 2023 11:36:12 GMT + tkapias + + + + + + + + ... + + + + + +``` + + +## To be done + +Some repositories do not offer Releases but will update Tags to signify a milestone. +- See if I can add an option to track tags. \ No newline at end of file