Zweigbeschreibungen in Git

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.

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.

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.

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:

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.

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.

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.

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

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.

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.

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

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.

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.

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/

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.