# -*- coding: utf-8 mode: markdown -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8
##@creator: jclain
##@created: 27/04/2016 03:19
##@modifier: jclain
##@changecount: 1
##@tags:
##@title: udist

{{{
udist: gestion d'une distribution upstream

Des fichiers de configuration (par exemple) sont distribués par un partenaire,
et il faut maintenir des modifications locales, tout en acceptant les mises à
jour provenant de l'upstream. Ce script aide à maintenir un tel scénario.

En général, la distribution upstream identifie les fichiers modifiables en leur
donnant une extension particulière, par exemple 'file.origine' ou 'file.default'
La liste des extensions reconnues est spécifiée avec l'option -s. Lors de leur
intégration dans le répertoire local, ces fichiers sont copiés sans cette
extension.

Terminologie: Les fichiers pour lesquels il faut maintenir une version locale
sont appelés 'fichiers locaux', qu'ils viennent de la distribution upstream ou
non. Les autres fichiers qui proviennent de la distribution sont appelés
'fichiers upstream'.

USAGE
    udist cmd [options]

OPTIONS COMMUNES
    -s .EXT
        Ajouter une extension à la liste des extensions reconnues comme contenu
        original modifiable dans la distribution upstream. Par défaut, les
        extensions suivantes sont reconnues:
            .udist .origine .default
        Cette option peut être utilisée autant de fois que nécessaire.
    --clear-origexts
        Supprimer la liste par défaut des extensions origines. Cette option doit
        être spécifiée avant l'option -s pour construire une nouvelle liste.
        La liste des extensions ne doit pas être vide. Si c'est le cas, elle est
        modifiée pour contenir l'unique élément (.udist)
    -d WORKDIR
        Spécifier le répertoire de travail. Par défaut, la racine du répertoire
        de travail est cherchée à partir du répertoire courant.
    --help
        Afficher l'aide détaillée de la commande spécifiée

COMMANDES
    init [WORKDIR [ARCHIVE]]
        Initialiser un répertoire de travail pour contenir une distribution
        upstream

    upstream-new, new SRCDIR|ARCHIVE [WORKDIR]
        Intégrer une nouvelle distribution upstream.
        Les nouveaux fichiers sont copiés tout de suite dans le répertoire de
        travail. Par contre, les modifications ne sont intégrées qu'avec la
        commande patch
    upstream-clear, clear [WORKDIR]
        Supprimer tous les fichiers non modifiés de l'upstream.

    local-create, create FILE
        Créer et/ou identifier FILE comme une modification locale par rapport à
        l'upstream.
    local-edit, edit FILE
        S'assurer que local-create a été exécuté si nécessaire pour FILE, puis
        l'éditer avec vim

    local-copy, cp SRCFILE DESTFILE
    local-move, mv SRCFILE DESTFILE
    local-remove, rm FILE
        Frontend pour respectivement cp, mv et rm. Ces commandes agissent aussi
        sur les fichiers orig et de tag.

    local-tag, tag FILE TAG
        Faire une copie du fichier local avec le tag spécifié. Si le fichier de
        tag existe déjà, il est écrasé.
    local-switch, switch TAG FILE
        Sélectionner la copie avec le tag spécifié.

    local-put, put [WORKDIR] DESTDIR
        Copier tous les fichiers locaux dans DESTDIR, par exemple pour faire une
        sauvegarde. Si DESTDIR n'est pas spécifié, prendre la valeur de
        l'origine, affichée par local-list
    local-get, get [-l|-s] SRCDIR [WORKDIR]
        Opération inverse de local-put: intégrer tous les fichiers de SRCDIR
        comme fichiers locaux. Si SRCDIR n'est pas spécifié, prendre la valeur
        de l'origine, affichée par local-list
    local-list, list [WORKDIR]
        Lister tous les fichiers locaux. Les fichiers pour lesquels il faut
        intégrer une modification de l'upstream avec la commande local-patch
        sont identifiés visuellement.

    upstream-diff, udiff [FILE]
        Après intégration d'une nouvelle distribution upstream, afficher les
        modifications entre la nouvelle distribution upstream et l'ancienne pour
        tous les fichiers modifiables
    local-diff, ldiff [FILE]
        Afficher les modifications locales par rapport à l'upstream pour le(s)
        fichier(s) spécifié(s).
    local-patch, lpatch [FILE]
        Après intégration d'une nouvelle distribution upstream, appliquer au(x)
        le(s) fichier(s) spécifié(s) les modifications disponibles affichées par
        upstream-diff.
    local-forget, lforget [FILE]
        Après intégration d'une nouvelle distribution upstream, oublier les
        modifications disponibles pour le(s) fichier(s) spécifié(s).
}}}
