git-autoshare

A git clone wrapper that automatically uses --reference to save disk space and download time.

Contents

• Installation
• Usage
  • Configuration file
  • git autoshare-clone command
  • git autoshare-submodule-add command
  • git autoshare-prefetch command
  • Environment variables
• Credits

Installation

To install git-autoshare in a fancy way, we recommend using pipx.

After installing pipx simply run:

$ pipx install git-autoshare

To upgrade git-autoshare at any time:

$ pipx upgrade git-autoshare

If you want git autoshare-clone to be invoked transparently in place of git clone, create the following bash script, name it git, and place it in your PATH before /usr/bin/git:

#!/bin/bash
if [ "$1" == "clone" ]
then
    shift
    /usr/bin/git autoshare-clone "$@"
else
    /usr/bin/git "$@"
fi

Usage

Configuration file

To configure it, create a file named git-autoshare/repos.yml in your user configuration directory (often ~/.config on Linux). This file must have the following structre:

host:
    repo:
        orgs:
            - organization
            - ...
        private: (True|False)
    ...:
...:

It lists all git hosts, repositories, and organizations that are subject to the sharing of git objects. Here is an example:

github.com:
    odoo:
        orgs:
            - odoo
            - OCA
    enterprise:
        orgs:
            - odoo
            - acsone
        private: True
    mis-builder:
        # shortcut to provides organizations
        - OCA
        - acsone

Note the use of the private option, used to force fetching using the ssh protocol.

It is also possible to use * as a wildcard for repository name, to have autoshare applied to all repos of some organizations:

github.com:
    "*":
        orgs:
            - odoo
            - OCA
            - acsone
        private: True

Note

In this configuration, git-autoshare-prefetch without arguments will not fetch any wildcard repo. This could be improved in the future to refetch repos that are already present in cache.

git autoshare-clone command

If configured like the example above, when you git clone the odoo or mis-builder repositories from one of these github organizations, git autoshare-clone will automatically insert the --reference option in the git clone command. For example:

$ git autoshare-clone https://github.com/odoo/odoo

will be transformed into:

$ /usr/bin/git clone --reference ~/.cache/git-autoshare/github.com/odoo https://github.com/odoo/odoo

git autoshare-submodule-add command

Same as git autoshare-clone command, you can add submodules with a reference. for example:

$ git autoshare-submodule-add https://github.com/odoo/odoo ./odoo

will be transformed into:

$ /usr/bin/git submodule add --reference ~/.cache/git-autoshare/github.com/odoo https://github.com/odoo/odoo ./odoo

git autoshare-prefetch command

The autoshare-prefetch command is mostly meant to be run in a cron job:

$ git autoshare-prefetch --quiet

will update the cache directory by fetching all repositories mentioned in repos.yml.

It can also prefetch one single repository, for example:

$ git autoshare-prefetch https://github.com/odoo/odoo.git

Environment variables

The cache directory is named git-autoshare where appdirs.user_cache_dir is (usually ~/.cache/git-autoshare/). This location can be configured with the GIT_AUTOSHARE_CACHE_DIR environment variable.

The default configuration file is named repos.yml where appdirs.user_config_dir is (usually ~/.config/git-autoshare/). This location can be configured with the GIT_AUTOSHARE_CONFIG_DIR environment variable.

By default git-autoshare invokes git as /usr/bin/git. This can be configured with the GIT_AUTOSHARE_GIT_BIN environment variable.

Credits

Author:

• Stéphane Bidoul (ACSONE)

Contributors

• Simone Orsi (Camptocamp)
• Mykhailo Panarin

Maintainer:

This project is maintained by ACSONE SA/NV.