mirror of
https://github.com/lilydjwg/nvchecker
synced 2024-12-12 09:45:29 +00:00
372 lines
14 KiB
ReStructuredText
372 lines
14 KiB
ReStructuredText
**nvchecker** (short for *new version checker*) is for checking if a new version of some software has been released.
|
|
|
|
.. image:: https://travis-ci.org/lilydjwg/nvchecker.svg
|
|
:alt: Build Status
|
|
:target: https://travis-ci.org/lilydjwg/nvchecker
|
|
.. image:: https://badge.fury.io/py/nvchecker.svg
|
|
:alt: PyPI version
|
|
:target: http://badge.fury.io/py/nvchecker
|
|
|
|
Contents
|
|
========
|
|
|
|
* `Dependency <#dependency>`_
|
|
* `Running <#running>`_
|
|
* `Version Record Files <#version-record-files>`_
|
|
|
|
* `The nvtake Command <#the-nvtake-command>`_
|
|
|
|
* `Version Source Files <#version-source-files>`_
|
|
|
|
* `Configuration Section <#configuration-section>`_
|
|
* `Search in a Webpage <#search-in-a-webpage>`_
|
|
* `Find with a Command <#find-with-a-command>`_
|
|
* `Check AUR <#check-aur>`_
|
|
* `Check GitHub <#check-github>`_
|
|
* `Check BitBucket <#check-bitbucket>`_
|
|
* `Check GitLab <#check-gitlab>`_
|
|
* `Check PyPI <#check-pypi>`_
|
|
* `Check RubyGems <#check-rubygems>`_
|
|
* `Check NPM Registry <#check-npm-registry>`_
|
|
* `Check Hackage <#check-hackage>`_
|
|
* `Check CPAN <#check-cpan>`_
|
|
* `Check Packagist <#check-packagist>`_
|
|
* `Check Local Pacman Database <#check-local-pacman-database>`_
|
|
* `Check Arch Linux official packages <#check-arch-linux-official-packages>`_
|
|
* `Check Google Code (hg repository) <#check-google-code-hg-repository>`_
|
|
* `Check Google Code (svn repository) <#check-google-code-svn-repository>`_
|
|
* `Manually updating <#manually-updating>`_
|
|
* `Version Control System (VCS) (git, hg, svn, bzr) <#version-control-system-vcs-git-hg-svn-bzr>`_
|
|
* `Other <#other>`_
|
|
|
|
* `Bugs <#bugs>`_
|
|
* `Footnotes <#footnotes>`_
|
|
|
|
Dependency
|
|
==========
|
|
- Python 3
|
|
- Tornado
|
|
- Optional pycurl
|
|
- All commands used in your version source files
|
|
|
|
Running
|
|
=======
|
|
To see available options::
|
|
|
|
./nvchecker --help
|
|
|
|
Run with one or more software version source files::
|
|
|
|
./nvchecker source_file
|
|
|
|
You normally will like to specify some "version record files"; see below.
|
|
|
|
Version Record Files
|
|
====================
|
|
Version record files record which version of the software you know or is available. They are simple key-value pairs of ``(name, version)`` seperated by a space\ [v0.3]_::
|
|
|
|
fcitx 4.2.7
|
|
google-chrome 27.0.1453.93-200836
|
|
vim 7.3.1024
|
|
|
|
Say you've got a version record file called ``old_ver.txt`` which records all your watched software and their versions, as well as some configuration entries. To update it using ``nvchecker``::
|
|
|
|
./nvchecker source.ini
|
|
|
|
See what are updated with ``nvcmp``::
|
|
|
|
./nvcmp source.ini
|
|
|
|
Manually compare the two files for updates (assuming they are sorted alphabetically; files generated by ``nvchecker`` are already sorted)::
|
|
|
|
comm -13 old_ver.txt new_ver.txt
|
|
# or say that in English:
|
|
comm -13 old_ver.txt new_ver.txt | awk '{print $1 " has updated to version " $2 "."}'
|
|
# show both old and new versions
|
|
join old_ver.txt new_ver.txt | awk '$2 != $3'
|
|
|
|
The ``nvtake`` Command
|
|
----------------------
|
|
This command helps to manage version record files. It reads both old and new version record files, and a list of names given on the commandline. It then update the versions of those names in the old version record file.
|
|
|
|
This helps when you have known (and processed) some of the updated software, but not all. You can tell nvchecker that via this command instead of editing the file by hand.
|
|
|
|
This command will help most if you specify where you version record files are in your config file. See below for how to use a config file.
|
|
|
|
Version Source Files
|
|
====================
|
|
The software version source files are in ini format. *Section names* is the name of the software. Following fields are used to tell nvchecker how to determine the current version of that software.
|
|
|
|
See ``sample_source.ini`` for an example.
|
|
|
|
Configuration Section
|
|
---------------------
|
|
A special section named ``__config__`` is special, it provides some configuration options\ [v0.4]_.
|
|
|
|
Relative path are relative to the source files, and ``~`` and environmental variables are expanded.
|
|
|
|
Currently supported options are:
|
|
|
|
oldver
|
|
Specify a version record file containing the old version info.
|
|
|
|
newver
|
|
Specify a version record file to store the new version info.
|
|
|
|
sort_version_key
|
|
Sort the version string using this key function. Choose between ``parse_version`` and
|
|
``vercmp``. Default value is ``parse_version``. ``parse_version`` use
|
|
``pkg_resources.parse_version``. ``vercmp`` use ``pyalpm.vercmp``.
|
|
|
|
|
|
Search in a Webpage
|
|
-------------------
|
|
Search through a specific webpage for the version string. This type of version finding has these fields:
|
|
|
|
url
|
|
The URL of the webpage to fetch.
|
|
|
|
encoding
|
|
(*Optional*) The character encoding of the webpage, if ``latin1`` is not appropriate.
|
|
|
|
regex
|
|
A regular expression used to find the version string.
|
|
|
|
It can have zero or one capture group. The capture group or the whole match is the version string.
|
|
|
|
When multiple version strings are found, the maximum of those is chosen.
|
|
|
|
proxy
|
|
The HTTP proxy to use. The format is ``host:port``, e.g. ``localhost:8087``. This requires `pycurl <http://pycurl.sourceforge.net/>`_.
|
|
|
|
user_agent
|
|
The ``User-Agent`` header value to use. Use something more like a tool (e.g. ``curl/7.40.0``) in Europe or the real web page won't get through because cookie policies (SourceForge has this issue).
|
|
|
|
sort_version_key
|
|
Sort the version string using this key function. Choose between ``parse_version`` and
|
|
``vercmp``. Default value is ``parse_version``. ``parse_version`` use
|
|
``pkg_resources.parse_version``. ``vercmp`` use ``pyalpm.vercmp``.
|
|
|
|
Find with a Command
|
|
-------------------
|
|
Use a shell command line to get the version. The output is striped first, so trailing newlines do not bother.
|
|
|
|
cmd
|
|
The command line to use. This will run with the system's standard shell (i.e. ``/bin/sh``).
|
|
|
|
Check AUR
|
|
---------
|
|
Check `Arch User Repository <https://aur.archlinux.org/>`_ for updates.
|
|
|
|
aur
|
|
The package name in AUR. If empty, use the name of software (the *section name*).
|
|
|
|
strip-release
|
|
Strip the release part.
|
|
|
|
Check GitHub
|
|
------------
|
|
Check `GitHub <https://github.com/>`_ for updates. The version returned is in date format ``%Y%m%d``, e.g. ``20130701``.
|
|
|
|
github
|
|
The github repository, with author, e.g. ``lilydjwg/nvchecker``.
|
|
|
|
branch
|
|
Which branch to track? Default: ``master``.
|
|
|
|
use_latest_release
|
|
Set this to ``true`` to check for the latest release on GitHub. An annotated
|
|
tag creates a "release" on GitHub. It's not the same with git tags, which
|
|
includes both annotated tags and lightweight ones.
|
|
|
|
use_max_tag
|
|
Set this to ``true`` to check for the max tag on GitHub. Unlike ``use_latest_release``,
|
|
this option includes both annotated tags and lightweight ones, and return the biggest one
|
|
sorted by ``pkg_resources.parse_version``.
|
|
|
|
ignored_tags
|
|
Ignore certain tags while computing the max tag. Tags are separate by
|
|
whitespaces. This option must be used together with ``use_max_tag``. This can
|
|
be useful to avoid some known badly versioned tags, so the newer tags won't
|
|
be "overridden" by the old broken ones.
|
|
|
|
sort_version_key
|
|
Sort the version string using this key function. Choose between ``parse_version`` and
|
|
``vercmp``. Default value is ``parse_version``. ``parse_version`` use
|
|
``pkg_resources.parse_version``. ``vercmp`` use ``pyalpm.vercmp``.
|
|
|
|
An environment variable ``NVCHECKER_GITHUB_TOKEN`` can be set to a GitHub OAuth token in order to request more frequently than anonymously.
|
|
|
|
Check BitBucket
|
|
---------------
|
|
Check `BitBucket <https://bitbucket.org/>`_ for updates. The version returned is in date format ``%Y%m%d``, e.g. ``20130701``.
|
|
|
|
bitbucket
|
|
The bitbucket repository, with author, e.g. ``lilydjwg/dotvim``.
|
|
|
|
branch
|
|
Which branch to track? Default is the repository's default.
|
|
|
|
use_max_tag
|
|
Set this to ``true`` to check for the max tag on BitBucket. Will return the biggest one
|
|
sorted by ``pkg_resources.parse_version``.
|
|
|
|
ignored_tags
|
|
Ignore certain tags while computing the max tag. Tags are separate by
|
|
whitespaces. This option must be used together with ``use_max_tag``. This can
|
|
be useful to avoid some known badly versioned tags, so the newer tags won't
|
|
be "overridden" by the old broken ones.
|
|
|
|
sort_version_key
|
|
Sort the version string using this key function. Choose between ``parse_version`` and
|
|
``vercmp``. Default value is ``parse_version``. ``parse_version`` use
|
|
``pkg_resources.parse_version``. ``vercmp`` use ``pyalpm.vercmp``.
|
|
|
|
Check GitLab
|
|
-------------
|
|
Check `GitLab <https://gitlab.com/>`_ for updates. The version returned is in date format ``%Y%m%d``, e.g. ``20130701``.
|
|
|
|
gitlab
|
|
The gitlab repository, with author, e.g. ``Deepin/deepin-music``.
|
|
|
|
branch
|
|
Which branch to track? Default: ``master``.
|
|
|
|
use_max_tag
|
|
Set this to ``true`` to check for the max tag on BitBucket. Will return the biggest one
|
|
sorted by ``pkg_resources.parse_version``.
|
|
|
|
ignored_tags
|
|
Ignore certain tags while computing the max tag. Tags are separate by
|
|
whitespaces. This option must be used together with ``use_max_tag``. This can
|
|
be useful to avoid some known badly versioned tags, so the newer tags won't
|
|
be "overridden" by the old broken ones.
|
|
|
|
sort_version_key
|
|
Sort the version string using this key function. Choose between ``parse_version`` and
|
|
``vercmp``. Default value is ``parse_version``. ``parse_version`` use
|
|
``pkg_resources.parse_version``. ``vercmp`` use ``pyalpm.vercmp``.
|
|
|
|
host
|
|
Hostname for self-hosted GitLab instance.
|
|
|
|
token
|
|
GitLab authorization token used to call the API. If not specified, an environment variable ``NVCHECKER_GITLAB_TOKEN_host`` must provide that token. The ``host`` part is the uppercased version of the ``host`` setting, with dots (``.``) and slashes (``/``) replaced by underscores (``_``), e.g. ``NVCHECKER_GITLAB_TOKEN_GITLAB_COM``.
|
|
|
|
Authenticated only.
|
|
|
|
Check PyPI
|
|
----------
|
|
Check `PyPI <https://pypi.python.org/>`_ for updates.
|
|
|
|
pypi
|
|
The name used on PyPI, e.g. ``PySide``.
|
|
|
|
Check RubyGems
|
|
--------------
|
|
Check `RubyGems <https://rubygems.org/>`_ for updates.
|
|
|
|
gems
|
|
The name used on RubyGems, e.g. ``sass``.
|
|
|
|
Check NPM Registry
|
|
------------------
|
|
Check `NPM Registry <https://registry.npmjs.org/>`_ for updates.
|
|
|
|
npm
|
|
The name used on NPM Registry, e.g. ``coffee-script``.
|
|
|
|
Check Hackage
|
|
-------------
|
|
Check `Hackage <https://hackage.haskell.org/>`_ for updates.
|
|
|
|
hackage
|
|
The name used on Hackage, e.g. ``pandoc``.
|
|
|
|
Check CPAN
|
|
--------------
|
|
Check `MetaCPAN <https://metacpan.org/>`_ for updates.
|
|
|
|
cpan
|
|
The name used on CPAN, e.g. ``YAML``.
|
|
|
|
Check Packagist
|
|
---------------
|
|
Check `Packagist <https://packagist.org/>`_ for updates.
|
|
|
|
packagist
|
|
The name used on Packagist, e.g. ``monolog/monolog``.
|
|
|
|
Check Local Pacman Database
|
|
---------------------------
|
|
This is used when you run ``nvchecker`` on an Arch Linux system and the program always keeps up with a package in your configured repositories for `Pacman`_.
|
|
|
|
pacman
|
|
The package name to reference to.
|
|
|
|
strip-release
|
|
Strip the release part.
|
|
|
|
Check Arch Linux official packages
|
|
----------------------------------
|
|
This enables you to track the update of `Arch Linux official packages <https://www.archlinux.org/packages/>`_, without needing of pacman and an updated local Pacman databases.
|
|
|
|
archpkg
|
|
Name of the Arch Linux package.
|
|
|
|
strip-release
|
|
Strip the release part.
|
|
|
|
Check Google Code (hg repository)
|
|
---------------------------------
|
|
Check a mercurial (hg) repository on `Google Code <https://code.google.com/>`_ for updates. The version returned is in date format ``%Y%m%d``, e.g. ``20130701``.
|
|
|
|
gcode_hg
|
|
The name used on Google Code, e.g. ``chromium-compact-language-detector``.
|
|
|
|
Check Google Code (svn repository)
|
|
----------------------------------
|
|
Check a subversion (svn) repository on `Google Code <https://code.google.com/>`_ for updates. The version returned is the svn resivion number.
|
|
|
|
gcode_svn
|
|
The name used on Google Code, e.g. ``cld2``.
|
|
|
|
Manually updating
|
|
-----------------
|
|
This enables you to manually specify the version (maybe because you want to approve each release before it gets to the script).
|
|
|
|
manual
|
|
The version string.
|
|
|
|
Version Control System (VCS) (git, hg, svn, bzr)
|
|
------------------------------------------------
|
|
Check a VCS repo for new commits. The version returned is currently not related to the version of the software and will increase whenever the referred VCS branch changes. This is mainly for Arch Linux.
|
|
|
|
vcs
|
|
The url of the remote VCS repo, using the same syntax with a VCS url in PKGBUILD (`Pacman`_'s build script). The first VCS url found in the source array of the PKGBUILD will be used if this is left blank. (Note: for a blank ``vcs`` setting to work correctly, the PKGBUILD has to be in a directory with the name of the software under the path where nvchecker is run. Also, all the commands, if any, needed when sourcing the PKGBUILD need to be installed).
|
|
|
|
use_max_tag
|
|
Set this to ``true`` to check for the max tag. Currently only supported for ``git``.
|
|
This option returns the biggest tag sorted by ``pkg_resources.parse_version``.
|
|
|
|
ignored_tags
|
|
Ignore certain tags while computing the max tag. Tags are separate by
|
|
whitespaces. This option must be used together with ``use_max_tag``. This can
|
|
be useful to avoid some known badly versioned tags, so the newer tags won't
|
|
be "overridden" by the old broken ones.
|
|
|
|
Other
|
|
-----
|
|
More to come. Send me a patch or pull request if you can't wait and have written one yourself :-)
|
|
|
|
Bugs
|
|
====
|
|
* Finish writing results even on Ctrl-C or other interruption.
|
|
|
|
Footnotes
|
|
=========
|
|
.. [v0.3] Note: with nvchecker <= 0.2, there are one more colon each line. You can use ``sed -i 's/://' FILES...`` to remove them.
|
|
.. [v0.4] This is added in version 0.4, and old command-line options are removed.
|
|
|
|
.. _Pacman: https://wiki.archlinux.org/index.php/Pacman
|