readme update
Signed-off-by: Tomasz Kapias <tkapias@git.tkapias.net>
This commit is contained in:
parent
d46989a92c
commit
2d8b963916
87
README.md
87
README.md
|
|
@ -1,3 +1,90 @@
|
||||||
# gh-starred-to-opml
|
# 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.
|
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 `<outline text="">` will provide the category's name.
|
||||||
|
- `<dateCreated>` & `<dateModified>` 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
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<opml version="2.0">
|
||||||
|
<head>
|
||||||
|
<title>gh_starred_tkapias_favorites.opml</title>
|
||||||
|
<dateCreated>Fri, 06 Sep 2019 19:35:09 GMT</dateCreated>
|
||||||
|
<dateModified>Sun, 12 Feb 2023 11:36:12 GMT</dateModified>
|
||||||
|
<ownerName>tkapias</ownerName>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<outline text="Github - favorites - tkapias">
|
||||||
|
<outline title="01mf02/jaq" text="01mf02/jaq" type="rss" version="ATOM1" description="A jq clone focussed on correctness, speed, and simplicity" xmlUrl="https://github.com/01mf02/jaq/releases.atom" htmlUrl="https://github.com/01mf02/jaq"></outline>
|
||||||
|
<outline title="Airblader/xedgewarp" text="Airblader/xedgewarp" type="rss" version="ATOM1" description="Effortlessly move your cursor across monitors of different resolutions and alignments" xmlUrl="https://github.com/Airblader/xedgewarp/releases.atom" htmlUrl="https://github.com/Airblader/xedgewarp"></outline>
|
||||||
|
<outline title="AlexandrePTJ/kemai" text="AlexandrePTJ/kemai" type="rss" version="ATOM1" description="Kimai desktop client" xmlUrl="https://github.com/AlexandrePTJ/kemai/releases.atom" htmlUrl="https://github.com/AlexandrePTJ/kemai"></outline>
|
||||||
|
<outline title="Alexey-T/CudaText" text="Alexey-T/CudaText" type="rss" version="ATOM1" description="Cross-platform text editor, written in Lazarus" xmlUrl="https://github.com/Alexey-T/CudaText/releases.atom" htmlUrl="https://github.com/Alexey-T/CudaText"></outline>
|
||||||
|
...
|
||||||
|
<outline title="zabbix/zabbix" text="zabbix/zabbix" type="rss" version="ATOM1" description="Real-time monitoring of IT components and services, such as networks, servers, VMs, applications and the cloud." xmlUrl="https://github.com/zabbix/zabbix/releases.atom" htmlUrl="https://github.com/zabbix/zabbix"></outline>
|
||||||
|
<outline title="zammad/zammad" text="zammad/zammad" type="rss" version="ATOM1" description="Zammad is a web based open source helpdesk/customer support system" xmlUrl="https://github.com/zammad/zammad/releases.atom" htmlUrl="https://github.com/zammad/zammad"></outline>
|
||||||
|
</outline>
|
||||||
|
</body>
|
||||||
|
</opml>
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
## 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.
|
||||||
Loading…
Reference in a new issue