================================
roster: manager an entity roster
================================

"Roster" is the name used in XMPP for the contact list. In addition to list of contacts,
you have also data like subscription information or groups associated to a contact.

Groups are simple strings associated to one or more contacts (e.g. "friends" or "family").

Subscription is the mechanism to get presence information of an entity. When you add a
contact to your roster, most XMPP clients also do a presence subscription request, than
the entity may accept or deny. If a presence subscription is accepted, the subscribed user
can see when the other entity is online, and its presence status.

get
===

Show the current roster. By default only a display name and JIDs are displayed, but you
can increase verbosity to also display groups, or all other metadata.

The short name shown next to jid is either the ``name`` specified in roster, or the node
part of the jid. If none of them exist, only the entity JID is shown.

The following metadata may be displayed:

groups
  group the entity belong too
ask
  true if a presence subscription request has been sent (but not answered yet)
from
  the contact has a subscription to user presence (i.e. your contact can see when you're
  online and your presence status)
to
  the user has a subscription to the contact presence (i.e. you can see when you're
  contact is online and his/her presence status)

examples
--------

Get roster of default profile and display groups::

  $ jp roster get -v

Get roster of default profile and display all metadata::

  $ jp roster get -vv

Get roster or default profile and show the result in JSON::

  $ jp roster get -O json

set
===

Set metadata for a roster entity. Only ``name`` and ``groups`` can be set, ``name`` being
the user chosed name to use with a contact.

By default, values are appended, i.e. if ``name`` is not set it won't delete existing one,
and ``groups`` are appended to existing one. However, if you use the ``-R, --replace``
option, former values will be entirely replaced by given ones (i.e. if you don't use ``-n
NAME, --name NAME`` option, the former one will be deleted, and any former group no added
using ``-g GROUP, --group GROUP`` will be removed).

examples
--------

Set a name used to privately identify your contact Louise::

  $ jp roster set -n Enjolras louise@example.net

Replace all groups of Pierre, to add him only to ``friends`` and ``housemates``::

  $ jp roster set --replace -g friends -g housemates pierre@example.net

stats
=====

Show some statistics about the profile roster. The number of contacts per server is shown,
with a percentage of contacts on this server compared to the total number of contacts.
This can notably be helpful to see if there is a concentration of your contacts in a
specific server or gateway.

Other more or less useful numbers are shown, they are self explaining.

example
-------

Get statistic for the default profile::

  $ jp roster stats

purge
=====

This command is used to remove from the roster all contacts which have no subscription or
only partial subscription.

By default, only contacts without subscription at all are removed. With ``--no_from`` you
also remove contacts which have no subscription to you (but you have a subscription to
them), and with ``--no_to`` you also remove contacts that you are not subscribed to (but
who are subscribed to you).

example
-------

Remove all contacts from default profile which have no subscription at all or from which
the default profile is not subscribed to::

  $ jp roster purge --no_to

resync
======

SàT uses `roster versioning`_ to optimize the synchronisation of roster with server on
client connection. This means that once the roster has been retrieved, on each following
connection, only the difference of contacts (i.e. which new or removed contacts) is
received.

This command does a full resynchronisation of the roster, or in other words it requests
the whole roster and save it, replacing the list built with versioning. ``resync`` is
mostly useful for developers and end-user should not need this command, as roster
versioning is supposed to work fine and the roster should be synchronised correctly on
startup. But if for any reason you suspect that your current roster list is corrupted, you
may use it to be sure that a full resynchronisation is done.

.. _roster versioning: https://tools.ietf.org/html/rfc6121#section-2.6

exemple
-------

Do a full resynchronisation of default profile's roster::

  $ jp roster resync