PageRenderTime 31ms CodeModel.GetById 20ms RepoModel.GetById 0ms app.codeStats 0ms

/README.rst

https://gitlab.com/gallaecio/chakraversiontracker
ReStructuredText | 245 lines | 167 code | 78 blank | 0 comment | 0 complexity | 5dc7e32ff478ee13cd19f250c6575033 MD5 | raw file
  1. Chakra Version Tracker
  2. ======================
  3. `Chakra Version Tracker <https://gitlab.com/gallaecio/chakraversiontracker>`_
  4. is a project that provides a command-line tool to query `Chakra
  5. <https://chakralinux.org/>`_ packages in `rolling repositories
  6. <http://goo.gl/DSFlMl>`_ that are out of date.
  7. Requirements
  8. ------------
  9. - `Python 3 <https://docs.python.org/3/>`_
  10. .. note:: If you really need a Python 2 version let us know and we will
  11. consider providing support for both versions, but to make things simpler
  12. for us we currently support Python 3 only.
  13. - `beautifulsoup4 <https://www.crummy.com/software/BeautifulSoup/bs4/doc/>`_
  14. - `jinja2 <http://jinja.pocoo.org/docs/dev/>`_
  15. - `lxml <http://lxml.de/>`_
  16. - `sphinx-argparse <https://sphinx-argparse.readthedocs.io/en/latest/>`_
  17. - `termcolor <https://pypi.python.org/pypi/termcolor>`_
  18. - `versiontracker <http://version-tracker.rtfd.io/>`_
  19. Installation
  20. ------------
  21. Installing with `pip <https://pip.pypa.io/en/stable/quickstart/>`_::
  22. pip install chakraversiontracker
  23. Installing from sources::
  24. python setup.py install
  25. Installing from sources for development (if you plan to extend tracked
  26. packages)::
  27. python setup.py develop
  28. Basic Usage
  29. -----------
  30. The `chakraversiontracker` command-line tool does not require any parameters::
  31. $ chakraversiontracker
  32. desktop:
  33. gsoap 2.8.33 2.8.34
  34. libguess 1.1 1.2
  35. It lists outdated packages in rolling repositories, showing for each package
  36. which version is currently in the repositories and which one is the latest
  37. stable version.
  38. If you want to get the name of the repository containing each package as well,
  39. use `-t repositories.cli`::
  40. $ chakraversiontracker -t packages.cli
  41. gsoap 2.8.33 2.8.34
  42. libguess 1.1 1.2
  43. Excluding Packages
  44. ------------------
  45. You can use the `-e` option to exclude a package from the results::
  46. $ chakraversiontracker -e gsoap
  47. desktop:
  48. libguess 1.1 1.2
  49. You can also use `-e` with a package tag to exclude all packages that have that
  50. tag. Tags are similar to Chakra package groups, only that they are specific to
  51. Chakra Version Tracker. Use `--list-tags` to get a list of available tags::
  52. $ chakraversiontracker --list-tags
  53. haskell
  54. kde-applications
  55. Selecting Repositories
  56. ----------------------
  57. By default, Chakra Version Tracker checks package versions in the rolling
  58. repositores: `testing`, `desktop`, `gtk`, `lib32`, `ccr`.
  59. You may manually specify one or more target repositories with `-r`. For
  60. example, to check package versions only in the `testing` and `desktop`
  61. repositories::
  62. chakraversiontracker -r testing -r desktop
  63. If you prefer, you may indicate repositories to exclude from the defalut list
  64. using `--exclude-repository`. For example, to check package versions in all
  65. rolling repositories but the `ccr`::
  66. chakraversiontracker --exclude-repository ccr
  67. Configuring the Output
  68. ----------------------
  69. The output of the `chakraversiontracker` command can be completely customized
  70. with a template. Use the `--list-templates` option to get a list of available
  71. built-in templates that you can pass to the `-t` option.
  72. Built-in templates may have either a `.txt` file extension or a `.cli` file
  73. extension. If you want to redirect the output of the command to a file, use the
  74. `-o` option and one of the `.txt` templates. `.cli` templates include data for
  75. terminal coloring that does not look well in plain text files.
  76. By default, a line in printed on the standard output with the progress of the
  77. query for the latest stable versions of tracked packages found in the specified
  78. repositories. If you are using a pipe to redirect the output to a file instead
  79. of using the `-o` option, you may want to use the `--no-progress` option to
  80. prevent the progress lines from being printed.
  81. You can write a custom template and pass its path to the command using the
  82. `-t` option to format the output data however you like. Your template must be a
  83. `Jinja2 <http://jinja.pocoo.org/docs/dev/templates/>`_ template that can use
  84. the following variables:
  85. - `packages` is a list of dictionaries represeting outdated packages. They are
  86. sorted alphabetically, and each dictionary contains the name of the package
  87. (`name`), the name of the repository that contains the package
  88. (`repository`), the version of the package found in the repositories
  89. (`repository_version`) and the latest stable version of the package
  90. (`upstream_version`).
  91. - `repositories` is an ordered dictionary (in the order in which the user
  92. specified the repositories) where keys are repository names and values are
  93. dictionaries with the same keys as the items in the `packages` list, with the
  94. exception of the `repository` key.
  95. - `date` is a dictionary with two keys: `local` and `utc`. They are `datetime`
  96. objects containing the local time and the UTC time, respectively.
  97. Extending Package Support
  98. --------------------------
  99. Chakra Version Tracker is not designed to let each user keep their custom
  100. package tracking data. Changes require you to *fork* the source code. If you
  101. do, we encourage you to `send us back your changes
  102. <https://gitlab.com/gallaecio/chakraversiontracker/merge_requests>`_ so that
  103. everyone can benefit from them.
  104. Use the following to clone the Git repository and install in development mode,
  105. so that your changes have effect on your system as soon as you save:
  106. .. code-block:: bash
  107. # If you have chakraversiontracker installed:
  108. sudo pip3 uninstall chakraversiontracker
  109. git clone https://gitlab.com/gallaecio/chakraversiontracker.git
  110. cd chakraversiontracker
  111. sudo python3 setup.py develop
  112. You can now work directly on the newly created folder, and whenever you execute
  113. `chakraversiontracker` the code in that folder will be executed.
  114. The data used to determine how to fetch version information of a supported
  115. package is defined in a JSON file, `chakraversiontracker/data.json`. This file
  116. indicates how packages in the Chakra repositories map to `Version Tracker
  117. <http://version-tracker.rtfd.io/>`_ software IDs.
  118. The data file contains a JSON object where keys are package names, and their
  119. value is a JSON object with settings::
  120. {
  121. "0ad": { },
  122. "0ad-data": { },
  123. }
  124. The object of each entry is usually empty, which indicates that the package is
  125. associated with the Version Tracker software ID with the same name::
  126. "0ad": {}
  127. If the package matches a different Version Tracker software ID, that ID is
  128. specified as the value of the `versiontracker` field::
  129. "0ad-data": { "versiontracker": "0ad" }
  130. If a package should not be tracked (e.g. no new releases are expected), set the
  131. `skip` field to `true`::
  132. "man2html": {
  133. "skip": true
  134. }
  135. If you want to ignore the package until a new version comes out (e.g. because
  136. the repositories are using a non-stable version that is newer than the stable
  137. version reported by Version Tracker), set the value of the `skip` field to the
  138. latest stable version reported by Version Tracker::
  139. "lockdev": {
  140. "skip": "1.0.3"
  141. }
  142. Packages can be tagged, so that you can easily ignore all packages with a given
  143. tag. To add one or more tags to a package, use the `tags` field::
  144. "dragon": {
  145. "tags": [
  146. "kde-applications"
  147. ]
  148. }
  149. Command Line Help
  150. -----------------
  151. .. argparse::
  152. :module: chakraversiontracker.__main__
  153. :func: _build_argument_parser
  154. :prog: chakraversiontracker
  155. :nodefault:
  156. Credits and License
  157. -------------------
  158. Chakra Version Tracker may be used under the terms of the :doc:`GNU Affero
  159. General Public License version 3 </license>` or later (AGPLv3+).
  160. For a list of authors who should be credited, see :doc:`/authors`.
  161. .. toctree::
  162. :hidden:
  163. self
  164. license
  165. authors