97 lines
4.4 KiB
Markdown
97 lines
4.4 KiB
Markdown
```text
|
||
[[[ SYNOPSIS ]]]
|
||
|
||
gancioff [options] <configuration file>
|
||
|
||
[[[ DESCRIPTION ]]]
|
||
|
||
This is GancioFF v0.1, a CLI PHP script that can be used to periodically
|
||
fetch the RSS feed from a Gancio¹ instance and post its entries – the events –
|
||
on the fediverse through a Mastodon account, keeping track of already posted
|
||
events in order to post only the new ones. It can be useful, for example, when
|
||
the admins of a Gancio instance chose not to use its federation feature
|
||
because it would be too heavy on its server: in this case GancioFF is quite
|
||
a light alternative, moving from the server running Gancio to the one running
|
||
Mastodon the burden of posting each event to all the instances that host at
|
||
least one follower, and of sending to them the image a Gancio user can and
|
||
almost always do attach to each event, because GancioFF will fetch it only
|
||
once and attach it to the corresponding Mastdon post.
|
||
GancioFF is meant to be periodically run (every half an hour, or so) by a
|
||
cron job or systemd timer or the likes (you can find a sample «gancioff.timer»
|
||
and a sample «gancioff.service» in the «systemd» directory).
|
||
In order to work, GancioFF needs a configuration file to be passed to it
|
||
as an argument on the command line, and the directory containing the specified
|
||
configuration file needs to be not only readable, but also writeable by the
|
||
user running GancioFF, because that’s where it will save the corresponding
|
||
state file that it will use to keep track of already posted events.
|
||
|
||
¹ https://gancio.org
|
||
|
||
[[[ CONFIGURATION FILE ]]]
|
||
|
||
The configuration file needs to be like this:
|
||
|
||
--- Example configuration file ---
|
||
# Lines beginnig with a «#» and empty lines will be ignored
|
||
|
||
# «feed_url» is required to specify the URL to fetch the RSS feed from,
|
||
# for example:
|
||
feed_url = https://gancio.some.domain/feed/rss?show_recurrent=true
|
||
|
||
# «fedi_hostname» is required to specify the hostname of the Mastodon instance
|
||
# you want to post to, for example:
|
||
fedi_hostname = mastodon.another.domain
|
||
|
||
# «fedi_token» is required to specify an «app token» to access the account
|
||
# that you want to use on the instance defined by «fedi_hostname». On Mastodon
|
||
# default web frontend you can get such a token under «Preferences» ->
|
||
# «Development», by clicking on the «New application» button; the new
|
||
# application should have at least the «write:statuses» privilege, and when
|
||
# you’ll be done setting it up, it will be listed under «Your applications»,
|
||
# and by clicking on its name you’ll be able to copy «Your access token» and
|
||
# paste it here; for example:
|
||
fedi_token = w6oQ_Ot2LSAm_Q31hrvp0asfl22ip3O4ipYq1kV1ceY
|
||
|
||
# «max_post_length» is optional and lets you override the automatically
|
||
# detected maximum length that a post can have on the instance specified with
|
||
# «fedi_hostname»; it can be used for testing purposes or just to keep the
|
||
# posts shorter than they would be otherwise. For example:
|
||
max_post_length = 840
|
||
--- End of example configuration file ---
|
||
|
||
[[[ OPTIONS ]]]
|
||
|
||
-h / --help
|
||
Show this help text and exit.
|
||
-p / --do-post
|
||
By default the first run with a given configuration file, i.e. when there’s
|
||
no corresponding state file yet, will be a “dry run”, that is: the script
|
||
will automatically avoid posting the events it finds in the feed, to avoid
|
||
flooding the timelines, but save their IDs in the state filejust as if «--do-not-post» or «-P» were given (see next option description). With «-p»
|
||
or «--do-post» it will post them, instead.
|
||
Also, if given after «-P» or «--do-not-post», it turns posting back on.
|
||
-I / --ignore-ids
|
||
Ignore events’ IDs, that is: don’t try to load and save already posted
|
||
events’ IDs from and to the state file.
|
||
-P / --do-not-post
|
||
Don’t post new events that could be found in the feed. Unless you also
|
||
specify «-I» or «--ignore-guids» (see previous option), this will add the IDs
|
||
of possible new events to the state file, just as if they were posted, so
|
||
those events will never be posted.
|
||
-v / --verbose
|
||
Show some more messages about what the script is doing.
|
||
--
|
||
Treat every possible subsequent argument as non-options. Useful only in the
|
||
very improbable case your config file is named «--help» or as another option.
|
||
|
||
[[[ EXIT VALUES ]]]
|
||
|
||
0: regular run
|
||
1: some error occurred
|
||
|
||
[[[ DISCLAIMER AND LICENSE ]]]
|
||
|
||
This program comes with ABSOLUTELY NO WARRANTY; for details see the source.
|
||
This is free software, and you are welcome to redistribute it under certain
|
||
conditions; see <http://www.gnu.org/licenses/> for details.
|
||
```
|