Metadata-Version: 2.1
Name: giternity
Version: 0.3
Summary: Mirror git repositories and retrieve metadata for cgit.
Home-page: https://github.com/rahiel/giternity
Author: Rahiel Kasim
Author-email: rahielkasim@gmail.com
License: GPLv3+
Keywords: giternity git mirror cgit
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: System :: Archiving :: Mirroring
Requires-Python: >=3.5
Requires-Dist: requests
Requires-Dist: toml

giternity
=========

|Version| |pyversions| |Downloads| |License|

Giternity is a tool to mirror git repositories from GitHub. You can
specify a username/organization to mirror all their repositories, or
just individual repos. It retrieves some repo metadata so they can be
nicely served with `cgit <https://git.zx2c4.com/cgit/about/>`__. Run
giternity periodically to update the mirrors.

An example result is `git.cpu.re <https://git.cpu.re/>`__. Follow the
`tutorial <https://www.rahielkasim.com/mirror-git-repositories-and-serve-them-with-cgit/>`__
to host your own.

Installation
============

Install giternity:

.. code:: shell

    sudo pip3 install giternity

You also need to have git installed.

Configuration
=============

The configuration file is at ``/etc/giternity.toml``:

.. code:: ini

    # path for the git mirrors
    git_data_path = "/srv/git/"

    # path for checkouts of the git mirrors (optional)
    # checkout_path = "/srv/git_checkout/"

    # public URL of your cgit instance (optional)
    # cgit_url = "https://git.cpu.re/"

    [github]
    repositories = [
        "rahiel",
        "sunsistemo",
        "TeMPOraL/nyan-mode",
    ]

Set ``git_data_path`` to the path where you want to store the git
repositories. It will contain bare git repositories: the data you
usually see in the ``.git`` directory in your projects. To also have the
actual working files of the repos, set ``checkout_path`` to where to
keep them. If you'll be hosting the repos with cgit, set ``cgit_url`` to
the public URL.

In the ``[github]`` section you specify which repositories to mirror.
You list a username (``"rahiel"``) or an organization (``"sunsistemo"``)
to mirror all of their non-fork repositories. For individual repos
(``"TeMPOraL/nyan-mode"``) you specify them like ``owner/repo``.

With the configuration in place you simply run ``giternity``.

For convenience there is an automatic configuration that sets up a
separate system user, gives this user permissions to ``git_data_path``
(and to ``checkout_path`` if specified) and creates a cron job at
``/etc/cron.d/giternity`` to update the mirrors every hour. Apply these
defaults with:

.. code:: shell

    sudo giternity --configure

cgit
====

Your git mirrors are now suitable to serve with cgit. Customize your
``/etc/cgitrc`` as you like and add the following to the bottom:

.. code:: ini

    agefile=info/web/last-modified
    section-from-path=1
    scan-path=/srv/git/

where you replace ``/srv/git/`` with the ``git_data_path`` from your
``/etc/giternity.toml``.

.. |Version| image:: https://img.shields.io/pypi/v/giternity.svg
   :target: https://pypi.org/project/giternity/
.. |pyversions| image:: https://img.shields.io/pypi/pyversions/giternity.svg
   :target: https://pypi.org/project/giternity/
.. |Downloads| image:: https://www.cpu.re/static/giternity/downloads.svg
   :target: https://www.cpu.re/static/giternity/downloads-by-python-version.txt
.. |License| image:: https://img.shields.io/badge/License-GPLv3+-blue.svg
   :target: https://github.com/rahiel/giternity/blob/master/LICENSE.txt


