web-dev-qa-db-fra.com

Description des branches dans Git

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

Bien que j'essaie d'utiliser des noms descriptifs, travailler pendant un certain temps sur une seule branche m'empêche parfois de me rappeler pourquoi j'ai créé certaines des autres branches. J'essaie d'utiliser des noms descriptifs pour les branches, mais je pense qu'une "description" (petite note sur le but de la branche) serait bien. 

gitbranchtask-tracking
245
Noufal Ibrahim

Git 1.7.9 supporte cela. Notes de mise à jour 1.7.9 :

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

Vous pouvez voir cette fonctionnalité introduite en septembre 2011, avec commits 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 le rôle de la branche, qui sera utilisé 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 apportées entre deux commits dans la sortie standard et inclut l'URL donnée dans le récapitulatif généré.

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

173
Greg Hewgill

Si vous do finissez par utiliser le fichier README, créez un git alias modifying git checkout afin que votre README soit affiché à chaque changement 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 README de la branche vers laquelle vous basculez.

38
tta

La README suggérée par Chris J peut fonctionner, à condition qu’elle soit configurée avec un pilote de fusion personnalisé défini dans un .gitattribute.
De cette façon, la version locale de README est toujours conservée lors des fusions.

La "description" des branches est également appelée "commentaire" associé à ces métadonnées et n'est pas prise en charge.

Au moins, avec un fichier README, vous pouvez, pour n’importe quelle branche, effectuer les opérations suivantes:

$ git show myBranch:README

Si votre README se trouve dans le répertoire racine de votre REPO, il fonctionnera depuis n’importe quel chemin, car le chemin utilisé par git show est absolu dans le répertoire principal du référentiel en question.

28
VonC

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

Voici une fonction du shell permettant d’afficher des branches similaires à git branch mais avec des descriptions ajoutées.

# Shows branches with descriptions
function gb() {
  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 == $(git rev-parse --abbrev-ref HEAD) ]; then
      branch="* \033[0;32m$branch\033[0m"
     else
       branch="  $branch"
     fi
     echo -e "$branch \033[0;36m$desc\033[0m"
  done
}

Voici à quoi ressemble gb, affiché ici sous forme de texte au cas où l'image pourrit:

$ 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 voir les couleurs:

 enter image description here

25
jsageryd

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 me souviens de ce que les branches que j'ai créées font, mais mon équipe ne le peut certainement pas.
  2. README fichier pr. branche. C’est difficile lors des fusions: super-enclin à fusionner des conflits et nous allons extraire README des branches lorsque nous fusionnons des branches d’entités. Les différences entre les branches sont également pénibles.

Nous avons décidé de créer une branche Orphan branches-readme. Les branches orphelines sont des branches avec leur propre historique. Vous pouvez les connaître des branches gh-pages de Github. Cette branche orpheline contient un seul fichier README. Il a un contenu comme:

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

Il est Push-capable et fusion-friendly. Affichez le README à partir de n’importe quelle branche avec:

git show branches-readme:README

Les inconvénients sont que vous devez extraire la branche étrange Orphan lorsque vous souhaitez mettre à jour le README et que le README ne se met pas à jour automatiquement lorsque les branches sont renommées, que vous alliez ou partiez. C'est bien pour nous, cependant.

Faites-le 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 d'une équipe peuvent également créer leurs propres branches-$user branches orphelines décrivant leurs propres branches privées s'ils le souhaitent, tant qu'ils ne les envoient pas à l'équipe.

Avec des outils supplémentaires, cela pourrait également être intégré à la sortie de git branch. À cette fin, peut-être qu'un fichier README.yaml pourrait être considéré à la place d'un README en clair.

10
Peter V. Mørch
git config --global --add alias.about '!describe() { git config branch."$1".description; }; describe'

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

8
Felicio

Voici une implémentation possible de la commande git branches que Greg Hewgill a évoquée:

#!/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";
}
5
Owen

Vous pouvez joindre des commentaires aux tags:

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 conserver une balise commentée en tête de vos branches de sujet.

2
Jamey Hicks

Utilisation

git branch --list -v

pour afficher une branche en amont:

git branch --list -vv

Ajoutez -r pour afficher uniquement les télécommandes ou -a pour afficher les télécommandes et local.

1
Markus Hartman

Voici une gitalias qui vous permet de définir et de lire des descriptions sur la branche en cours:

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

Usage/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

Un merci spécial à @Felicio pour la réponse qui m'a permis de commencer.

1
Wayne Burkett

Je suis à peu près sûr que cette fonctionnalité n'est pas prise en charge pour le moment. Je pense que votre meilleur choix est de créer un fichier texte de description, un README, dans la branche contenant les informations souhaitées.

0
Chris J

Il suffit d'utiliser:

git config branch.<branch name>.description

Pour créditer le crédit dû: https://glebbahmutov.com/blog/git-branches-with-descriptions/

0
Caleb Miller

La réponse choisie me semble exagérée. Je serais enclin à maintenir un fichier de description par branche qui est un fichier contrôlé par une source normale, par exemple master.txt, dev.txt, etc., et s'il existe un nombre ou des branches trop compliqués, je créerais une hiérarchie pour mieux l'organiser.

0
pajato0