Descriptions des branches dans Git

Existe-t-il un moyen dans Git d'avoir une «description» pour les branches?

Pendant que j'essaie d'utiliser des noms descriptifs, travailler pendant un certain temps sur une seule branche atténue parfois ma mémoire des raisons pour lesquelles j'ai créé certaines des autres branches de sujet. J'essaie d'utiliser des noms descriptifs pour les branches, mais je pense qu'une «description» (brève note sur le but de la branche) serait bien.

Git 1.7.9 prend cela en charge. À partir des notes de version 1.7.9 :

 * "git branch --edit-description" peut être utilisé pour ajouter du texte descriptif
   pour expliquer en quoi consiste une branche thématique.

Vous pouvez voir cette fonctionnalité introduite en septembre 2011, avec les validations 6f9a332 , 739453a3 , b7200e8 :

struct branch_desc_cb {
  const char *config_name;
  const char *value;
};

--edit-description::

Ouvrez un éditeur et modifiez le texte pour expliquer à quoi sert la branche, à utiliser par diverses autres commandes (par exemple request-pull).

Notez que cela ne fonctionnera pas pour une branche HEAD détachée.

Cette description est utilisée par le script request-pull: voir commit c016814783 , mais aussi git merge --log.

request-pull est un script utilisé pour résumer les modifications entre deux validations de la sortie standard et inclut l'URL donnée dans le résumé généré.

[De @AchalDave] Malheureusement, vous ne pouvez pas pousser les descriptions car elles sont stockées dans votre configuration, ce qui la rend inutile pour documenter les branches d'une équipe.

Si vous finissez par utiliser le README, créez un alias git en le modifiant git checkoutpour que votre README s'affiche à chaque fois que vous changez de branche.

Par exemple, ajoutez ceci dans ~ / .gitconfig, sous [alias]

cor = !sh -c 'git checkout $1 && cat README' -

Après cela, vous pouvez exécuter git cor <branch_name>pour changer de branche et afficher le fichier README de la branche vers laquelle vous passez.

Utilisez git branch --edit-descriptionpour définir ou modifier une description de branche.

Voici une fonction shell pour afficher des branches similaires git branchmais avec des descriptions en annexe.

# Shows branches with descriptions
function gb() {
  current=$(git rev-parse --abbrev-ref HEAD)
  branches=$(git for-each-ref --format='%(refname)' refs/heads/ | sed 's|refs/heads/||')
  for branch in $branches; do
    desc=$(git config branch.$branch.description)
    if [ $branch == $current ]; then
      branch="* \033[0;32m$branch\033[0m"
     else
       branch="  $branch"
     fi
     echo -e "$branch \033[0;36m$desc\033[0m"
  done
}

Voici à quoi cela gbressemble, affiché ici sous forme de texte au cas où l'image pourrirait:

$ gb
* logging Log order details.  Waiting for clarification from business.
  master 
  sprocket Adding sprockets to the parts list.  Pending QA approval.

Et comme une image, vous pouvez donc voir les couleurs:

Le READMEsuggéré par Chris J peut fonctionner, à condition qu'il soit configuré avec un pilote de fusion personnalisé défini dans a.gitattribute .
De cette façon, la version locale de la READMEest toujours conservée lors des fusions.

La "description" des branches est également connue sous le nom de "commentaire" associé à ces métadonnées, et elle n'est pas prise en charge.

Au moins, avec un READMEfichier, vous pouvez, pour n'importe quelle branche, faire:

$ git show myBranch:README

Si votre fichier README se trouve dans le répertoire racine de votre REPO, il fonctionnera à partir de n'importe quel chemin, car le chemin utilisé par git showest un chemin absolu du répertoire supérieur dudit référentiel.

Il y a deux suggestions populaires ici:

1. git branch --edit-description: Nous n'aimons pas cela parce que vous ne pouvez pas le pousser. Peut-être que je peux me souvenir de ce que font les branches que j'ai créées, mais mon équipe ne le peut certainement pas.
2. READMEfichier pr. branche. C'est une douleur pendant les fusions: super-enclin à fusionner les conflits et nous tirerons READMEdes branches lorsque nous fusionnerons les branches de fonctionnalités. Les différences entre les branches sont également une douleur.

Nous avons décidé de créer une branches-readmebranche orpheline . Les branches orphelines sont des branches avec leur propre histoire distincte - vous les connaissez peut-être dans les gh-pagesbranches de Github . Cette branche orpheline contient un seul READMEfichier. Il a des contenus comme:

master:
    The default branch
mojolicious:
    Start using Mojolicious
branch-whatever:
    Description of the whatever branch

Il est poussable et convivial. Visualisez le READMEdepuis n'importe quelle branche avec:

git show branches-readme:README

Les inconvénients sont que vous devez extraire la branche orpheline étrange lorsque vous souhaitez mettre à jour le READMEet READMEne se met pas automatiquement à jour lorsque les branches sont renommées, vont ou viennent. C'est bien pour nous, cependant.

Faites comme:

git checkout --orphan branches-readme
# All the files from the old branch are marked for addition - skip that
git reset --hard
# There are no files yet - an empty branch
ls
vi README
# put in contents similar to above
git add README
git commit -m "Initial description of the branches we already have"
git push origin branches-readme
# get all your original files back
git checkout master

De même, les membres individuels de l'équipe peuvent également créer leurs propres branches-$userbranches orphelines décrivant leurs propres branches privées s'ils le souhaitent, tant qu'ils ne les poussent pas vers l'équipe.

Avec un outillage supplémentaire, cela pourrait également être intégré à la sortie de git branch. À cette fin, un README.yamldossier pourrait peut-être être envisagé au lieu d'une simple README.

git config --global --add alias.about '!describe() { git config branch."$1".description; }; describe'

La commande définira une option globale alias.aboutcomme expression shell. L'exécution git about <branch>dans un référentiel affichera la description de la branche si elle est définie.

Voici une implémentation possible de la git branchescommande à laquelle Greg Hewgill a fait allusion:

#!/usr/bin/perl

sub clean {
    map { s/^[\s\*]*\s// } @_;
    map { s/\s*$// } @_;
    return @_;
}

sub descr {
    $_ = `git config branch.@_.description`;
    s/\s*$//;
    return $_;
};
sub indent {
    $_ = shift;
    s/^/      /mg;
    return $_;
};

my @branches = clean `git branch --color=never --list`;
my %merged = map { $_ => 1 } clean `git branch --color=never --merged`;

for my $branch (@branches) {
    my $asis = `git branch --list --color=always $branch`;
    $asis =~ s/\s*$//;
    print "  $asis";
    print " \033[33m(merged)\033[0m" if ($merged{$branch} and $branch ne "master");
    print "\n";

    print indent descr $branch;
    print "\n";
    print "\n";
}

Voici un git aliasqui vous permet à la fois de définir et de lire des descriptions sur la branche actuelle:

git config --global --add alias.about '!describe() { msg="$1"; git config branch."$(git rev-parse --abbrev-ref HEAD)".description ${msg:+"$msg"}; }; describe'

Utilisation / exemples:

(develop) $ git about
(develop) $ git about message
(develop) $ git about
message
(develop) $ git about "this is a new message"
(develop) $ git about
this is a new message
(develop) $ git checkout -b test_branch
Switched to a new branch 'test_branch'
(test_branch) $ git about
(test_branch) $ git about "this is the test branch"
(test_branch) $ git about
this is the test branch
(test_branch) $ git checkout -
Switched to branch 'develop'
Your branch is up to date with 'origin/develop'.
(develop) $ git about
this is a new message

Un merci spécial à @Felicio pour la réponse qui m'a donné le coup d'envoi.

Vous pouvez joindre des commentaires aux balises:

git tag -m 'this was a very good commit' tag1

Par convention, vous pouvez avoir des balises liées aux noms de vos branches ou vous pouvez utiliser la balise -f pour garder une balise commentée en tête de vos branches de sujet.

Dites que vous voulez créer une branche

git branch branch-20200328
git notes add branch-20200328 -m "This branch is for whatever"
git notes show branch-20200328

Je suis presque sûr que cette fonctionnalité n'est pas actuellement prise en charge. Je pense que votre meilleur pari est de créer un fichier texte de description, un README en gros, dans la branche qui contient les informations que vous souhaitez.

La réponse choisie me semble exagérée. Je serais enclin à maintenir un par fichier de description sarment qui est un fichier contrôlé de source normale, disons master.txt, dev.txtetc. et s'il y a un nombre difficile à manier ou branches je crée une hiérarchie pour mieux l' organiser.

Utilisez simplement:

git config branch.<branch name>.description

Pour donner du crédit là où le crédit est dû: https://glebbahmutov.com/blog/git-branches-with-descriptions/

Utilisation

git branch --list -v

pour afficher une branche en amont:

git branch --list -vv

Ajouter -rpour afficher uniquement les télécommandes ou -apour afficher les télécommandes et les locaux.