Zweigbeschreibungen in Git

282

Gibt es in Git eine Möglichkeit, eine 'Beschreibung' für Zweige zu haben?

Während ich versuche, beschreibende Namen zu verwenden, dämpft das Arbeiten für eine Weile an einem einzelnen Zweig manchmal meine Erinnerung daran, warum ich einige der anderen Themenzweige erstellt habe. Ich versuche, beschreibende Namen für die Zweige zu verwenden, aber ich denke, eine 'Beschreibung' (kurze Anmerkung zum Zweck des Zweigs) wäre schön.

Noufal Ibrahim
quelle
1
Ich hatte ein ähnliches Problem . Ich benutze diese Datei, um Zweige zu dokumentieren und warum sie existieren (unter anderem).
Themis
2
Dies wäre eine wirklich nützliche Funktion. git branch -a könnte die Beschreibungen neben den Filialnamen anzeigen. Vielleicht unterstützen Git-Notizen in Zukunft sowohl Notizen zu Zweigen als auch Commits?
Jhabbott
1
Zweigbeschreibungen können nicht verschoben werden, daher sind sie ziemlich nutzlos, es sei denn, Sie möchten Nachrichten an sich selbst senden.
Nurettin
@nurettin Stimmt, aber meine Anfrage war sowieso für private Sachen. Ich wollte mich nur daran erinnern, warum ich den Ast geschnitten habe.
Noufal Ibrahim

Antworten:

200

Git 1.7.9 unterstützt dies. Aus den Versionshinweisen zu 1.7.9 :

 * "git branch --edit-description" kann verwendet werden, um beschreibenden Text hinzuzufügen
   um zu erklären, worum es in einem Themenbereich geht.

Sie können diese Funktion sehen, die bereits im September 2011 mit den Commits 6f9a332 , 739453a3 , b7200e8 eingeführt wurde :

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

--edit-description::

Öffnen Sie einen Editor und bearbeiten Sie den Text, um zu erklären, wozu der Zweig dient, der von verschiedenen anderen Befehlen (z request-pull. B. ) verwendet werden soll.

Beachten Sie, dass dies für einen getrennten HEAD-Zweig nicht funktioniert.

Diese Beschreibung wird vom Skript request-pull verwendet: siehe commit c016814783 , aber auch git merge --log.

request-pull ist ein Skript, das verwendet wird, um die Änderungen zwischen zwei Festschreibungen an der Standardausgabe zusammenzufassen und die angegebene URL in die generierte Zusammenfassung aufzunehmen.

[Von @AchalDave] Leider können Sie Beschreibungen nicht pushen, da sie in Ihrer Konfiguration gespeichert sind, sodass sie für die Dokumentation von Zweigen in einem Team unbrauchbar sind.

Greg Hewgill
quelle
17
@Owen: Der einzige Weg, den ich im Moment kenne, besteht darin git config branch.topic.description, die Beschreibung für den Zweig anzuzeigen topic. Es ist in der .git/configDatei gespeichert .
Greg Hewgill
12
@ GregHewgill Danke. Mit ein paar Aliasnamen ist das eigentlich keine schlechte Art, es anzuzeigen. Nun, wenn nur git branchdie Beschreibungen in der Liste zeigen würde ...
Owen
4
Zu diesem Zeitpunkt scheint der im vorherigen Kommentar zitierte Inhalt nicht verfügbar zu sein, aber dies scheint ähnlich zu sein: gist.github.com/carlosayam/5316969
pfalcon
166
Leider können Sie Beschreibungen nicht pushen, da sie in Ihrer Konfiguration gespeichert sind, sodass sie für die Dokumentation von Zweigen in einem Team unbrauchbar sind.
Achal Dave
2
@ PedroRodrigues leider ist Ihr Hauptlink gebrochen
UpAndAdam
40

Wenn Sie Sie die README am Ende mit, erstellen Sie eine git alias modifiziert , git checkoutso dass Ihre README jedes Mal , wenn Zweige wechseln angezeigt wird.

Fügen Sie dies beispielsweise in ~ / .gitconfig unter [Alias] hinzu.

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

Danach können Sie den Zweig git cor <branch_name>wechseln und die README-Datei des Zweigs anzeigen, zu dem Sie wechseln.

tta
quelle
Für mich funktioniert die Variable $ 1 nicht - sie enthält nichts. Ich weiß nicht warum (ich benutze die Version 1.7.11-msysgit.1). Ich benutze stattdessen $ 0. Und alles ist gut.
Shytikov
@shytikov für Git-Aliase, die Argumente verwenden, verwende ich aus Gründen der Portabilität eine Schnellfunktion anstelle von " sh -c"; z.B,. alias = "!f() { git checkout "${1}" && cat README.md; }; f" (Klammern und Anführungszeichen sind in diesem Fall nicht erforderlich, nur der Vollständigkeit
halber
@ Michael_n Ihr Alias, ist das ein Bash-Alias ​​oder ein Git-Alias
UpAndAdam
Das einzige Problem ist, dass wenn README nicht in dem Ordner ist, in dem Sie sich beim Auschecken befinden, es sich nur beschwert.
UpAndAdam
@UpAndAdam Es ist ein Git-Alias, der in ~/.gitconfig, unter definiert ist [alias], und der Name des Alias ​​wird tatsächlich (und verständlicherweise verwirrend) aliasaus meiner tatsächlichen Konfiguration aufgerufen (ich hätte ihn umbenennen sollen, damit cordieses Beispiel konsistent ist). Mein eigentlicher aliasAlias ​​lautet: alias = "!f() { git config --get-regexp "^alias.${1}$" ; }; f" Verwendung: git alias {alias_name}oder git alias {alias_regexp}. Analog zum Bash- aliasBefehl $ alias llergibt sich zB (für mich) : alias ll='ls -l'; und $ git alias brergibt: alias.br branch -v --list(könnte auch verwenden: $ git alias 'b.*')
michael
31

Verwenden Sie git branch --edit-descriptiondiese Option, um eine Zweigbeschreibung festzulegen oder zu bearbeiten.

Hier ist eine Shell-Funktion zum Anzeigen von Zweigen ähnlich, git branchaber mit angehängten Beschreibungen.

# 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
}

So gbsieht es aus, hier als Text angezeigt, falls das Bild verrottet:

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

Und als Bild, damit Sie die Farben sehen können:

Geben Sie hier die Bildbeschreibung ein

jsageryd
quelle
Wie unterscheidet sich dies von der akzeptierten Antwort (mehr als ein Jahr zuvor veröffentlicht)?
Peter Mortensen
28

Der READMEvon Chris J vorgeschlagene kann funktionieren, vorausgesetzt, er wird mit einem benutzerdefinierten Zusammenführungstreiber eingerichtet, der in a definiert ist.gitattribute .
Auf diese Weise bleibt die lokale Version von READMEbei Zusammenführungen immer erhalten.

Die "Beschreibung" für Zweige wird auch als "Kommentar" bezeichnet, der diesen Metadaten zugeordnet ist, und wird nicht unterstützt.

Zumindest können Sie mit einer READMEDatei für jeden Zweig Folgendes ausführen:

$ git show myBranch:README

Befindet sich Ihre README-Datei im Stammverzeichnis Ihres REPO, funktioniert sie von jedem Pfad aus, da der von verwendete Pfad git showein absoluter Pfad aus dem obersten Verzeichnis des Repos ist.

VonC
quelle
3
Muss sich jeder im Team dessen bewusst sein und es in seinem .gitattribute individuell festlegen, wenn er es möchte? Wenn ja, scheint es mir schwierig zu sein, dies zu handhaben, und die Chancen, dass Leute es tatsächlich tun, wären gering.
Don Hatch
@DonHatch: Normalerweise checken Sie die .gitattributesDatei in Ihr Repository ein, also nein, es würde nur für alle funktionieren. Dies scheint jedoch beim Zusammenführen über einige webbasierte Schnittstellen nicht zu funktionieren, z. B. wenn Pull-Anforderungen in Azure DevOps verwendet werden.
Soren Bjornstad
19

Hier gibt es zwei beliebte Vorschläge:

  1. git branch --edit-description: Wir mögen das nicht, weil man es nicht schieben kann. Vielleicht kann ich mich daran erinnern, was die von mir erstellten Niederlassungen tun, aber mein Team kann es sicher nicht.
  2. READMEDatei pr. Ast. Dies ist ein Problem beim Zusammenführen: Sehr anfällig für das Zusammenführen von Konflikten, und wir werden READMEaus Zweigen ziehen, wenn wir Feature-Zweige zusammenführen. Diffs zwischen Zweigen sind auch ein Schmerz.

Wir haben beschlossen, eine verwaiste branches-readmeNiederlassung einzurichten . Waisenzweige sind Zweige mit einer eigenen Geschichte - Sie kennen sie möglicherweise aus Githubs gh-pagesZweigen. Dieser verwaiste Zweig enthält eine einzelne READMEDatei. Es hat Inhalte wie:

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

Es ist Push-fähig und zusammenführungsfreundlich. Zeigen Sie die READMEvon jedem Zweig mit:

git show branches-readme:README

Nachteile sind, dass Sie den seltsamen verwaisten Zweig auschecken müssen, wenn Sie den aktualisieren möchten, READMEund der READMEnicht automatisch aktualisiert wird, wenn Zweige umbenannt werden, kommen oder gehen. Das ist aber gut für uns.

Mach es wie:

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

In ähnlicher Weise können einzelne Teammitglieder auch ihre eigenen branches-$userverwaisten Zweige erstellen , die ihre eigenen privaten Zweige beschreiben, wenn sie möchten, sofern sie diese nicht an das Team weiterleiten .

Mit weiteren Werkzeugen könnte dies auch in die Ausgabe von integriert werden git branch. Zu diesem Zweck könnte möglicherweise eine README.yamlDatei anstelle einer Ebene betrachtet werden README.

Peter V. Mørch
quelle
Man könnte einfach die README im Master haben. Das würde Unordnung hinzufügen, aber immer zugänglich sein.
Peter - Monica
2
@ PeterA.Schneider: Sicher, aber das Hinzufügen eines neuen Zweigs würde ein Commit zum Master erfordern, obwohl die Änderung überhaupt nichts mit dem Master zu tun hat. Wenn Sie vom Master abzweigen, haben Sie außerdem eine Kopie der README-Datei in allen Zweigen, was ua ein Chaos ist.
Peter V. Mørch
10
git config --global --add alias.about '!describe() { git config branch."$1".description; }; describe'

Der Befehl definiert eine globale Option alias.aboutals Shell-Ausdruck. Laufen git about <branch>in einem Repository wird Zweig Beschreibung angezeigt , wenn gesetzt.

Felicio
quelle
4
Vielen Dank! Ich habe es geändert, damit es nur auf die Filiale schaut, auf der ich mich "!describe() { git config branch.\"$(git symbolic-ref --short -q HEAD)\".description; }; describe"
befinde
1
@aug - Ich musste die Backslashes vor den Argumentzitaten fallen lassen, damit dies funktioniert:git config --global --add alias.about '!describe() { git config branch."$(git symbolic-ref --short -q HEAD)".description; }; describe'
Tom Tresansky
5

Hier ist eine mögliche Implementierung des git branchesBefehls, auf den Greg Hewgill anspielte:

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

Hier ist eine git alias, mit der Sie Beschreibungen für den aktuellen Zweig festlegen und lesen können:

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

Verwendung / Beispiele:

(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

Besonderer Dank geht an @Felicio für die Antwort, mit der ich angefangen habe.

Wayne
quelle
Nett! Kann es zu Shell oder Ohmyzsh kompiliert werden?
mqliutie
2

Sie können Tags Kommentare hinzufügen:

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

Konventionell könnten Sie Tags haben, die sich auf Ihre Filialnamen beziehen, oder Sie könnten Tag -f verwenden, um ein kommentiertes Tag am Kopf Ihrer Themenzweige zu halten.

Jamey Hicks
quelle
13
Dies ist nicht ideal, weil es nicht den Leiter der Niederlassung verfolgt
AndyL
1

Angenommen, Sie möchten einen Zweig erstellen

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

Ich bin mir ziemlich sicher, dass diese Funktion derzeit nicht unterstützt wird. Ich denke, Ihre beste Wahl ist es, eine Beschreibungstextdatei, im Grunde eine README-Datei, in dem Zweig zu erstellen, der die gewünschten Informationen enthält.

Chris J.
quelle
4
Ich müsste mir Sorgen machen, dass diese Datei nicht verzweigungsübergreifend zusammengeführt wird. Würde ich nicht?
Noufal Ibrahim
1
@KaspervandenBerg: Vielleicht hinterlasse einfach einen Kommentar, anstatt die -1-Karte herauszuziehen, und warte dann einige Zeit. Wenn der Fragesteller nicht bereit ist, den Beitrag zu ändern, aber du siehst, dass er / sie diese Seite in der Zwischenzeit besucht hat. buchstabiere es. Oder überprüfen Sie regelmäßig alle Ihre Antworten, um festzustellen, ob sie noch korrekt sind?
Sebastian Mach
1
@phresnel: guter Punkt; Meine Absicht war es, zukünftigen Fragestellern dieser Frage zu helfen und gute Antworten nach oben und falsche nach unten zu bringen. Es war nicht, Chris J zu "bestrafen" und ihn dazu zu bringen, seinen Ruf zu verlieren. Leider sagt die Seite, dass meine Stimme gesperrt ist :(.
Kasper van den Berg
1
@KaspervandenBerg: Ich habe dich ein bisschen schnell der Bestrafung verdächtigt, sorry.
Sebastian Mach
0

Die ausgewählte Antwort scheint mir übertrieben. Ich würde geneigt sein , eine pro Zweig Beschreibungsdatei zu erhalten , die eine normale Quelle gesteuert Datei ist, sagen wir master.txt, dev.txtusw. , und wenn es eine unhandliche Zahl oder Verzweigungen würde ich eine Hierarchie besser organisieren es schaffen.

pajato0
quelle
6
Dann müssten Sie sich Gedanken über das Zusammenführen dieser Dateien mit jedem anderen Zweig machen oder daran denken, diese zu verwenden, git show master:dev.txtdie nicht einfacher als die ausgewählte Antwort ist.
Sridhar Ratnakumar
0

Benutz einfach:

git config branch.<branch name>.description

Um Kredit zu geben, wo Kredit fällig ist: https://glebbahmutov.com/blog/git-branches-with-descriptions/

Caleb Miller
quelle
Dies wurde in einer Version von git hinzugefügt, die veröffentlicht wurde, nachdem ich die Frage hinzugefügt hatte. Die akzeptierte Antwort erwähnt dies.
Noufal Ibrahim
Ah ja. Es wird in den Kommentaren erwähnt.
Caleb Miller
Obwohl dies eine Abkürzung ist, ist dies nicht im Wesentlichen identisch mit der akzeptierten Antwort? - "Leider können Sie Beschreibungen nicht pushen, da sie in Ihrer Konfiguration gespeichert sind, sodass sie für die Dokumentation von Zweigen in einem Team unbrauchbar sind."
Peter Mortensen
-3

Verwenden

git branch --list -v

um einen vorgelagerten Zweig zu zeigen:

git branch --list -vv

Hinzufügen -r, um nur Fernbedienungen anzuzeigen oder -aum Fernbedienungen und lokale Anzeigen anzuzeigen.

Markus Hartman
quelle
Nützlich wie diese sind, suche ich nach etwas Benutzerdefiniertem. Eine Notiz, die einer Referenz beigefügt ist.
Noufal Ibrahim
2
Es werden keine Beschreibungen angezeigt. Ich denke, diese Antwort ist irreführend.
Pato Sandaña