Descrições de filiais no Git

Existe uma maneira no Git de ter uma 'descrição' para ramificações?

Enquanto tento usar nomes descritivos, trabalhar por um tempo em um único ramo às vezes diminui minha memória de por que fiz alguns dos outros tópicos. Eu tento usar nomes descritivos para os ramos, mas acho que uma 'descrição' (breve observação sobre o objetivo do ramo) seria legal.

O Git 1.7.9 suporta isso. Das notas de versão 1.7.9 :

 * "git branch --edit-description" pode ser usado para adicionar texto descritivo
   para explicar o que é uma ramificação de tópico.

Você pode ver esse recurso introduzido em setembro de 2011, com confirmações 6f9a332 , 739453a3 , b7200e8 :

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

--edit-description::

Abra um editor e edite o texto para explicar para que serve o ramo, para ser usado por vários outros comandos (por exemplo request-pull).

Observe que ele não funcionará para uma ramificação HEAD desanexada.

Essa descrição é usada pelo script request-pull: consulte commit c016814783 , mas também git merge --log.

request-pull é um script usado para resumir as alterações entre duas confirmações na saída padrão e inclui o URL fornecido no resumo gerado.

[De @AchalDave] Infelizmente, você não pode enviar descrições porque elas são armazenadas em sua configuração, tornando-a inútil para documentar ramificações em uma equipe.

Se você fazer acabar usando o README, criar um git apelido modificandogit checkout para que seu README é exibido toda vez que você mudar ramos.

Por exemplo, adicione isso em ~ / .gitconfig, em [alias]

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

Depois disso, você pode executar git cor <branch_name>para alternar a ramificação e exibir o README da ramificação para a qual está alternando.

Use git branch --edit-descriptionpara definir ou editar uma descrição da ramificação.

Aqui está uma função shell para mostrar ramificações semelhantes a, git branchmas com descrições anexadas.

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

Aqui está o que gbparece, mostrado aqui como texto, caso a imagem apodreça:

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

E como uma imagem, para que você possa ver as cores:

O READMEsugerido por Chris J pode funcionar, desde que configurado com um driver de mesclagem personalizado definido em a.gitattribute .
Dessa forma, a versão local do READMEsempre é preservada durante as mesclagens.

A "descrição" para ramificações também é conhecida como um "comentário" associado a esses metadados e não é suportada.

Pelo menos, com um READMEarquivo, você pode, para qualquer ramificação, fazer um:

$ git show myBranch:README

Se o seu README estiver no diretório raiz do seu REPO, ele funcionará em qualquer caminho, pois o caminho usado git showé absoluto no diretório superior do referido repositório.

Existem duas sugestões populares aqui:

1. git branch --edit-description: Nós não gostamos disso porque você não pode pressioná-lo. Talvez eu me lembre do que os ramos que criei fazem, mas minha equipe com certeza não consegue.
2. READMEarquivo pr. ramo. Isso é um problema durante as mesclagens: super-propenso a mesclar conflitos e estaremos entrando em READMEramificações quando mesclar ramificações de recursos. As diferenças entre os galhos também são uma dor.

Decidimos criar um branches-readmeramo órfão . Ramos órfãos são ramos com sua própria história separada - você pode conhecê-los dos gh-pagesramos do Github . Este ramo órfão contém um único READMEarquivo. Possui conteúdos como:

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

É capaz de empurrar e de mesclar. Veja o READMEde qualquer ramo com:

git show branches-readme:README

As desvantagens são que você precisa fazer check-out do ramo órfão estranho quando deseja atualizar o READMEeREADME não é atualizado automaticamente à medida que os ramos são renomeados, vêm ou vão. Isso é bom para nós, no entanto.

Faça como:

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

Da mesma forma, membros individuais da equipe também podem criar seus próprios branches-$user ramos órfãos, descrevendo seus próprios ramos particulares, se assim o desejarem, desde que não os enviem para a equipe.

Com outras ferramentas, isso também pode ser integrado à saída de git branch. Para esse fim, talvez um README.yamlarquivo possa ser considerado em vez de simples README.

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

O comando definirá uma opção global alias.aboutcomo expressão de shell. A execução git about <branch>em um repositório exibirá a descrição da ramificação, se configurada.

Aqui está uma possível implementação do git branchescomando que Greg Hewgill mencionou:

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

Aqui está um git aliasque permite definir e ler descrições no ramo atual:

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

Uso / exemplos:

(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

Agradecimentos especiais a @Felicio pela resposta que me iniciou.

Você pode anexar comentários às tags:

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

Por convenção, você pode ter tags relacionadas aos nomes de suas ramificações ou usar a tag -f para manter uma tag comentada no início das ramificações de tópicos.

Digamos que você queira criar uma ramificação

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

Tenho certeza de que esse recurso não é suportado no momento. Acho que sua melhor aposta é criar um arquivo de texto de descrição, basicamente um README, no ramo que possui as informações que você deseja.

A resposta selecionada parece um exagero para mim. Eu estaria inclinado a manter um arquivo de descrição por ramo que é um arquivo normal controlado fonte, digamos master.txt, dev.txt, etc. e se houver um número de difícil controle ou ramos eu criar uma hierarquia para organizar melhor isso.

Apenas use:

git config branch.<branch name>.description

Para dar crédito onde o crédito é devido: https://glebbahmutov.com/blog/git-branches-with-descriptions/

Usar

git branch --list -v

para mostrar um ramo upstream:

git branch --list -vv

Adicione -rpara mostrar apenas controles remotos ou -apara mostrar controles remotos e local.