Opisy oddziałów w Git

Czy w Git istnieje sposób na „opis” gałęzi?

Podczas gdy próbuję używać opisowych nazw, praca przez pewien czas nad jedną gałęzią czasami tłumi moją pamięć o tym, dlaczego stworzyłem inne gałęzie tematyczne. Staram się używać opisowych nazw gałęzi, ale myślę, że „opis” (krótka uwaga na temat celu gałęzi) byłby miły.

Git 1.7.9 obsługuje to. Z informacji o wersji 1.7.9 :

 * Do dodania tekstu opisowego można użyć „git branch --edit-description”
   aby wyjaśnić, na czym polega gałąź tematyczna.

Możesz zobaczyć tę funkcję wprowadzoną we wrześniu 2011 r. Z zatwierdzeniami 6f9a332 , 739453a3 , b7200e8 :

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

--edit-description::

Otwórz edytor i edytuj tekst, aby wyjaśnić, do czego służy gałąź, do użycia przez różne inne polecenia (np request-pull.).

Pamiętaj, że to nie będzie działać dla odłączonej gałęzi HEAD.

Ten opis jest używany przez skrypt request-pull: patrz zatwierdzenie c016814783 , ale także git merge --log.

request-pull jest skryptem używanym do podsumowania zmian między dwoma zatwierdzeniami standardowego wyjścia i zawiera podany adres URL w wygenerowanym podsumowaniu.

[From @AchalDave] Niestety, nie możesz wypychać opisów, ponieważ są one przechowywane w twojej konfiguracji, co czyni je bezużytecznymi ze względu na dokumentowanie oddziałów w zespole.

Jeśli nie kończy się przy użyciu README utworzyć alias git modyfikujących git checkoutżeby README jest wyświetlany przy każdym włączeniu oddziałów.

Na przykład dodaj to w ~ / .gitconfig, w [alias]

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

Następnie możesz uruchomić, git cor <branch_name>aby zmienić gałąź i wyświetlić README gałęzi, na którą się przełączasz.

Służy git branch --edit-descriptiondo ustawiania lub edycji opisu oddziału.

Oto funkcja powłoki wyświetlająca gałęzie podobne do, git branchale z dołączonymi opisami.

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

Oto, jak to gbwygląda, pokazane tutaj jako tekst na wypadek, gdyby obraz zgnił:

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

I jako obraz, dzięki czemu można zobaczyć kolory:

READMESugerowane przez Chris J może pracować, pod warunkiem, że jest ustawiony w sterowniku zwyczaj łączenia zdefiniowanego w sposób.gitattribute .
W ten sposób lokalna wersja READMEjest zawsze zachowywana podczas scalania.

„Opis” gałęzi jest również znany jako „komentarz” powiązany z tymi metadanymi i nie jest obsługiwany.

Przy pomocy READMEpliku możesz dla dowolnej gałęzi wykonać:

$ git show myBranch:README

Jeśli README znajduje się w katalogu głównym REPO, będzie działał z dowolnej ścieżki, ponieważ ścieżka używana przez git showjest absolutna z górnego katalogu wspomnianego repozytorium.

Istnieją tutaj dwie popularne sugestie:

1. git branch --edit-description: Nie podoba nam się to, ponieważ nie można tego naciskać. Może pamiętam, co robią gałęzie, które utworzyłem, ale mój zespół na pewno nie.
2. READMEplik pr. gałąź. Jest to uciążliwe podczas łączenia: bardzo podatne na łączenie konfliktów, a my będziemy przyciągać READMEz gałęzi, kiedy łączymy gałęzie cech. Różnice między gałęziami również powodują ból.

Zdecydowaliśmy się stworzyć branches-readmegałąź osieroconą . Gałęzie sieroce są gałęziami z własną odrębną historią - możesz je poznać z gh-pagesgałęzi Githuba . Ta gałąź sieroca zawiera jeden READMEplik. Zawiera treści takie jak:

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

Jest przystosowany do pchania i łączenia. Przeglądaj READMEz dowolnego oddziału za pomocą:

git show branches-readme:README

Wady polegają na tym, że musisz sprawdzić dziwną gałąź osieroconą, gdy chcesz zaktualizować, READMEi READMEnie aktualizuje się automatycznie, gdy gałęzie są zmieniane, przychodzą lub odchodzą. Dla nas to w porządku.

Zrób to jak:

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

Podobnie, poszczególni członkowie zespołu mogą również tworzyć własne branches-$useroddziały osierocone, opisując własne oddziały prywatne, jeśli chcą, pod warunkiem, że nie popchną ich do zespołu.

Przy dalszym oprzyrządowaniu można to również zintegrować z wydajnością git branch. W tym celu może README.yamlbyć rozważony plik zamiast zwykłego README.

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

Polecenie zdefiniuje opcję globalną alias.aboutjako wyrażenie powłoki. Uruchomienie git about <branch>w repozytorium wyświetli opis oddziału, jeśli jest ustawiony.

Oto możliwa implementacja git branchespolecenia, o którym wspominał Greg Hewgill:

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

Oto, git aliasco pozwala zarówno ustawiać, jak i czytać opisy w bieżącym oddziale:

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

Zastosowanie / przykłady:

(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

Specjalne podziękowania dla @Felicio za odpowiedź, która mnie rozpoczęła.

Do tagów możesz dołączać komentarze:

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

Zgodnie z konwencją, możesz mieć tagi związane z nazwami swoich gałęzi lub możesz użyć tagu -f, aby utrzymać komentarz z komentarzem na początku gałęzi tematu.

Powiedz, że chcesz utworzyć oddział

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

Jestem pewien, że ta funkcja nie jest obecnie obsługiwana. Myślę, że najlepszym rozwiązaniem jest utworzenie pliku tekstowego opisu, w zasadzie README, w gałęzi zawierającej potrzebne informacje.

Wybrana odpowiedź wydaje mi się przesadna. Byłbym skłonny do utrzymania na gałąź plik opisu, który jest normalne źródło sterowane plik, powiedzmy master.txt, dev.txtitp, a jeśli istnieje liczba nieporęczny lub gałęzie Chciałbym stworzyć hierarchię lepiej organizować je.

Po prostu użyj:

git config branch.<branch name>.description

Aby przyznać kredyt w przypadku, gdy należy się kredyt: https://glebbahmutov.com/blog/git-branches-with-descriptions/

Posługiwać się

git branch --list -v

aby wyświetlić odgałęzienie:

git branch --list -vv

Dodaj, -raby pokazać tylko piloty lub -aaby pokazać piloty i lokalnie.