Descriptions des branches dans Git


282

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.


1
J'ai eu un problème similaire . J'utilise ce fichier pour documenter les branches et pourquoi elles existent (entre autres).
themis

2
Ce serait une fonctionnalité vraiment utile. git branch -a pourrait afficher les descriptions à côté des noms de branche. Peut-être que git notes supportera les notes sur les branches ainsi que les commits à l'avenir?
jhabbott

1
Les descriptions de branche ne peuvent pas être poussées, elles sont donc assez inutiles à moins que vous ne vouliez vous envoyer des messages.
nurettin

@nurettin Vrai mais ma demande était quand même pour des trucs privés. Je voulais juste me rappeler pourquoi j'ai coupé la branche.
Noufal Ibrahim

Réponses:


200

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.


17
@Owen: La seule façon que je connaisse pour le moment est d'utiliser git config branch.topic.descriptionpour afficher la description de la branche topic. Il est stocké dans le .git/configfichier.
Greg Hewgill

12
@GregHewgill Merci. Avec quelques alias, ce n'est pas une mauvaise façon de le voir. Maintenant, si seulement git branchmontrait les descriptions dans la liste ...
Owen

4
Pour le moment, l'essentiel cité dans le commentaire précédent ne semble pas être disponible, mais cela semble similaire: gist.github.com/carlosayam/5316969
pfalcon

166
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.
Achal Dave

2
@PedroRodrigues malheureusement, votre lien essentiel est rompu
UpAndAdam

40

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.


Pour moi, la variable $ 1 ne fonctionne pas - elle ne contient rien. Je ne sais pas pourquoi (j'utilise la version 1.7.11-msysgit.1). J'utilise 0 $ à la place. Et tout va bien.
shytikov

@shytikov pour les alias git qui utilisent des arguments, pour la portabilité, j'utilise une fonction rapide au lieu de " sh -c"; par exemple,. alias = "!f() { git checkout "${1}" && cat README.md; }; f" (crochets et guillemets inutiles dans ce cas, juste inclus pour être complets au cas où ils seraient nécessaires pour quelque chose de plus compliqué.)
michael

@michael_n votre alias, est-ce un alias bash ou un alias git
UpAndAdam

Le seul problème est que si README n'est pas dans le dossier dans lequel vous vous trouvez lorsque vous passez à la caisse, il se plaint simplement.
UpAndAdam

@UpAndAdam c'est un alias git, défini dans ~/.gitconfig, sous [alias], et le nom de l'alias est en fait (et c'est compréhensible de façon confuse) aliasdepuis ma configuration actuelle (j'aurais dû le renommer corpour que cet exemple soit cohérent). Mon aliasalias actuel est: alias = "!f() { git config --get-regexp "^alias.${1}$" ; }; f" Utilisation: git alias {alias_name}ou git alias {alias_regexp}. Analogue à la aliascommande bash , par exemple, $ alias lldonne (pour moi) alias ll='ls -l':; et les $ git alias brrendements: alias.br branch -v --list(pourrait aussi utiliser: $ git alias 'b.*')
michael

31

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:

entrez la description de l'image ici


En quoi est-ce différent de la réponse acceptée (publiée plus d'un an auparavant)?
Peter Mortensen


28

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.


3
Est-ce que tout le monde dans l'équipe doit être conscient de cela et le mettre dans son attribut .git individuellement s'il le veut? Si tel est le cas, il me semble que ce serait difficile à gérer, et les chances des gens de le faire seraient minces.
Don Hatch

@DonHatch: Vous archivez normalement le .gitattributesfichier dans votre référentiel, donc non, cela fonctionnerait pour tout le monde. Malheureusement, cela ne semble pas fonctionner lors de la fusion via certaines interfaces Web, par exemple lors de l'utilisation de demandes d'extraction dans Azure DevOps.
Soren Bjornstad

19

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.


On pourrait juste avoir le README en master. Cela ajouterait de l'encombrement mais serait toujours accessible.
Peter - Réintègre Monica le

2
@ PeterA.Schneider: Bien sûr, mais l'ajout d'une nouvelle branche nécessiterait un commit sur master même si le changement n'a rien à voir avec master. En outre, lors de la dérivation du maître, vous aurez une copie du fichier README dans toutes les branches, ce qui est notamment le gâchis.
Peter V. Mørch

10
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.


4
Merci! Je l' ai changé il regarde juste la branche que je suis sur -"!describe() { git config branch.\"$(git symbolic-ref --short -q HEAD)\".description; }; describe"
août

1
@aug - J'avais besoin de supprimer les barres obliques inverses devant les citations d'argument pour que cela fonctionne:git config --global --add alias.about '!describe() { git config branch."$(git symbolic-ref --short -q HEAD)".description; }; describe'
Tom Tresansky

5

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";
}

4

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.


Agréable! Peut-il être compilé en shell ou ohmyzsh?
mqliutie

2

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.


13
ce n'est pas idéal car il ne suit pas le chef de branche
AndyL

1

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

0

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.


4
Je devrais m'inquiéter de ne pas fusionner ce fichier entre les branches. N'est-ce pas?
Noufal Ibrahim

1
@KaspervandenBerg: Peut-être laissez-vous simplement un commentaire au lieu de retirer la carte -1, puis attendez un certain temps, et si le demandeur n'est pas disposé à modifier le message, mais vous voyez qu'il / elle a visité ce site en attendant, épelle-le. Ou vérifiez - vous régulièrement toutes vos réponses pour voir si elles sont toujours correctes?
Sebastian Mach

1
@phresnel: bon point; mon intention était d'aider les futurs demandeurs de cette question et d'avoir de bonnes réponses en haut et des mauvaises en bas, ce n'était pas pour "punir" Chris J et lui faire perdre sa réputation. Malheureusement, le site dit que mon vote est verrouillé :(.
Kasper van den Berg

1
@KaspervandenBerg: J'ai été un peu prompt à vous soupçonner de punir, désolé.
Sebastian Mach

0

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.


6
Ensuite, vous devrez vous soucier de la fusion de ces fichiers dans toutes les autres branches, ou n'oubliez pas d'utiliser git show master:dev.txtce qui n'est pas plus simple que la réponse sélectionnée.
Sridhar Ratnakumar

0

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/


Cela a été ajouté dans une version de git qui a été publiée après avoir ajouté la question. La réponse acceptée le mentionne.
Noufal Ibrahim

Ah oui. Il est mentionné dans les commentaires.
Caleb Miller


-3

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.


Aussi utiles soient-ils, je recherche quelque chose de personnalisé. Une note quelconque attachée à une référence.
Noufal Ibrahim

2
Il ne montre pas de descriptions. Je pense que cette réponse est trompeuse.
Pato Sandaña
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.