GancioF2F/README.md

[[[ 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.