Descrizioni delle filiali in Git

C'è un modo in Git di avere una "descrizione" per i rami?

Mentre provo a usare nomi descrittivi, lavorare per un po 'su un singolo ramo a volte smorza la mia memoria del perché ho creato alcuni degli altri rami dell'argomento. Cerco di usare nomi descrittivi per i rami, ma penso che una 'descrizione' (breve nota sullo scopo del ramo) sarebbe gradita.

Git 1.7.9 supporta questo. Dalle note di rilascio 1.7.9 :

 * "git branch --edit-description" può essere usato per aggiungere un testo descrittivo
   per spiegare di cosa tratta un argomento.

Puoi vedere quella funzione introdotta a settembre 2011, con commit 6f9a332 , 739453a3 , b7200e8 :

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

--edit-description::

Apri un editor e modifica il testo per spiegare a cosa serve il ramo, da utilizzare con vari altri comandi (ad es request-pull.).

Si noti che non funzionerà per un ramo HEAD distaccato.

Tale descrizione viene utilizzata dallo script request-pull: consultare commit c016814783 , ma anche git merge --log.

request-pull è uno script utilizzato per riepilogare le modifiche tra due commit nell'output standard e include l'URL specificato nel riepilogo generato.

[Da @AchalDave] Sfortunatamente, non puoi inviare descrizioni poiché sono archiviate nella tua configurazione, rendendola inutile per il bene di documentare i rami in una squadra.

Se non finisce per utilizzare il file README, creare un alias Git che modificano git checkoutin modo che il README viene visualizzata ogni volta che si accende rami.

Ad esempio, aggiungilo in ~ / .gitconfig, sotto [alias]

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

Successivamente, è possibile eseguire git cor <branch_name>per cambiare ramo e visualizzare il file README del ramo in cui si sta passando.

Utilizzare git branch --edit-descriptionper impostare o modificare una descrizione del ramo.

Ecco una funzione shell per mostrare rami simili git branchma con descrizioni allegate.

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

Ecco come gbappare, mostrato qui come testo nel caso in cui l'immagine marcisca:

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

E come immagine, così puoi vedere i colori:

Il READMEsuggerito da Chris J può funzionare, purché sia ​​configurato con un driver di unione personalizzato definito in a.gitattribute .
In questo modo, la versione locale di READMEviene sempre conservata durante le fusioni.

La "descrizione" per i rami è anche conosciuta come un "commento" associato a quei metadati e non è supportato.

Almeno, con un READMEfile, puoi, per qualsiasi ramo, fare un:

$ git show myBranch:README

Se il tuo README si trova nella directory principale del tuo REPO, funzionerà da qualsiasi percorso, poiché il percorso utilizzato da git showè assoluto dalla directory superiore di detto repository.

Ci sono due suggerimenti popolari qui:

1. git branch --edit-description: Non ci piace perché non puoi spingerlo. Forse riesco a ricordare cosa fanno i rami che ho creato, ma la mia squadra sicuramente non può.
2. READMEfile pr. ramo. Questo è un dolore durante le fusioni: super-incline a unire i conflitti e ci uniremo READMEdai rami quando uniremo i rami delle caratteristiche. Anche le differenze tra i rami sono un dolore.

Abbiamo deciso di creare un branches-readmeramo orfano . I rami orfani sono rami con una loro storia separata - potresti conoscerli dai gh-pagesrami di Github . Questo ramo orfano contiene un singolo READMEfile. Ha contenuti come:

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

È a portata di mano e si adatta alla fusione. Visualizza READMEda qualsiasi ramo con:

git show branches-readme:README

Gli svantaggi sono che è necessario verificare lo strano ramo orfano quando si desidera aggiornare READMEe READMEnon si aggiorna automaticamente quando i rami vengono rinominati, vengono o vanno. Per noi va bene.

Fallo come:

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

Allo stesso modo, i singoli membri del team possono anche creare i propri branches-$userrami orfani descrivendo i propri rami privati ​​se lo desiderano, purché non li spingano al team.

Con ulteriori strumenti questo potrebbe anche essere integrato con l'output di git branch. A tal fine, forse un README.yamlfile potrebbe essere considerato al posto di un semplice README.

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

Il comando definirà un'opzione globale alias.aboutcome espressione shell. L'esecuzione git about <branch>in un repository visualizzerà la descrizione del ramo se impostata.

Ecco una possibile implementazione del git branchescomando a cui Greg Hewgill ha accennato:

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

Ecco una git aliasche ti consente sia di impostare e leggere le descrizioni sul ramo corrente:

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

Uso / Esempi:

(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 ringraziamento speciale a @Felicio per la risposta che mi ha fatto iniziare.

È possibile allegare commenti ai tag:

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

Per convenzione, potresti avere tag relativi ai nomi delle tue filiali oppure puoi usare tag -f per mantenere un tag commentato all'inizio dei rami dell'argomento.

Di 'che vuoi creare un ramo

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

Sono abbastanza sicuro che questa funzione non sia attualmente supportata. Penso che la soluzione migliore sia quella di creare un file di testo descrittivo, in pratica un file README, nel ramo che contiene le informazioni desiderate.

La risposta selezionata mi sembra eccessiva. Sarei propenso a mantenere un file di descrizione per ogni ramo che è un normale file di origine controllata, per esempio master.txt, dev.txte così via, e se v'è un numero ingombrante o rami mi piacerebbe creare una gerarchia per meglio organizzarla.

Usa solo:

git config branch.<branch name>.description

Per dare credito quando è dovuto il credito: https://glebbahmutov.com/blog/git-branches-with-descriptions/

Uso

git branch --list -v

per mostrare un ramo a monte:

git branch --list -vv

Aggiungi -rper mostrare solo telecomandi o -aper mostrare telecomandi e locali.