Descripciones de ramas en Git

¿Hay alguna manera en Git de tener una 'descripción' para las ramas?

Si bien trato de usar nombres descriptivos, trabajar por un tiempo en una sola rama a veces amortigua mi memoria de por qué hice algunas de las otras ramas temáticas. Intento usar nombres descriptivos para las ramas, pero creo que una 'descripción' (nota breve sobre el propósito de la rama) sería buena.

Git 1.7.9 lo admite. De las notas de la versión 1.7.9 :

 * "git branch --edit-description" se puede usar para agregar texto descriptivo
   para explicar de qué trata una rama temática.

Puede ver esa característica introducida en septiembre de 2011, con commits 6f9a332 , 739453a3 , b7200e8 :

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

--edit-description::

Abra un editor y edite el texto para explicar para qué es la rama, para ser utilizado por varios otros comandos (por ejemplo request-pull).

Tenga en cuenta que no funcionará para una rama HEAD separada.

El script request-pull utiliza esa descripción: consulte commit c016814783 , pero también git merge --log.

request-pull es un script utilizado para resumir los cambios entre dos confirmaciones en la salida estándar e incluye la URL dada en el resumen generado.

[De @AchalDave] Desafortunadamente, no puede enviar descripciones ya que están almacenadas en su configuración, lo que lo hace inútil por el simple hecho de documentar ramas en un equipo.

Si no terminan usando el README, crear un alias de git modifican git checkoutpara que su README se visualiza cada vez que se enciende ramas.

Por ejemplo, agregue esto en ~ / .gitconfig, en [alias]

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

Después de esto, puede ejecutar git cor <branch_name>para cambiar de rama y mostrar el archivo README de la rama a la que está cambiando.

Use git branch --edit-descriptionpara establecer o editar una descripción de rama.

Aquí hay una función de shell para mostrar ramas similares git branchpero con descripciones adjuntas.

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

Esto es lo que gbparece, mostrado aquí como texto en caso de que la imagen se pudra:

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

Y como imagen, para que puedas ver los colores:

Lo READMEsugerido por Chris J puede funcionar, siempre que esté configurado con un controlador de fusión personalizado definido en a.gitattribute .
De esa manera, la versión local de la READMEsiempre se conserva durante las fusiones.

La "descripción" de las ramas también se conoce como un "comentario" asociado con esos metadatos, y no es compatible.

Al menos, con un READMEarchivo, puede, para cualquier rama, hacer:

$ git show myBranch:README

Si su archivo README se encuentra en el directorio raíz de su REPO, funcionará desde cualquier ruta, ya que la ruta utilizada por git showes absoluta desde el directorio superior de dicho repositorio.

Aquí hay dos sugerencias populares:

1. git branch --edit-description: No nos gusta esto porque no puedes presionarlo. Tal vez puedo recordar lo que hacen las ramas que creé, pero mi equipo no puede.
2. READMEarchivo pr. rama. Esto es un dolor durante las fusiones: es muy propenso a fusionar conflictos y nos retiraremos READMEde las ramas cuando fusionamos ramas de características. Las diferencias entre las ramas también son un dolor.

Hemos decidido crear una branches-readmerama huérfana . Las ramas huérfanas son ramas con su propia historia separada; puedes conocerlas de las gh-pagesramas de Github . Esta rama huérfana contiene un solo READMEarchivo. Tiene contenidos como:

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

Es empujable y fácil de combinar. Ver READMEdesde cualquier sucursal con:

git show branches-readme:README

Las desventajas son que debe pagar la rama huérfana extraña cuando desea actualizar el READMEy elREADME no se actualiza automáticamente a medida que las ramas cambian de nombre, van o vienen. Sin embargo, eso está bien para nosotros.

Hazlo 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

De manera similar, los miembros individuales del equipo también pueden crear sus propios branches-$user ramas huérfanas describiendo sus propias ramas privadas si lo desean, siempre que no los empujen al equipo.

Con herramientas adicionales esto también podría integrarse con la salida de git branch. Con ese fin, tal vez README.yamlpodría considerarse un archivo en lugar de un simple README.

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

El comando definirá una opción global alias.aboutcomo expresión de shell. Si se ejecuta git about <branch>en un repositorio, se mostrará la descripción de la rama si está establecida.

Aquí hay una posible implementación del git branchescomando al que Greg Hewgill aludió:

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

Aquí hay una git aliasque le permite establecer y leer descripciones en la rama actual:

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

Uso / ejemplos:

(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 agradecimiento especial a @Felicio por la respuesta que me ayudó a comenzar.

Puede adjuntar comentarios a las etiquetas:

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

Por convención, podría tener etiquetas relacionadas con los nombres de sus sucursales o podría usar la etiqueta -f para mantener una etiqueta comentada al frente de las ramas de sus temas.

Digamos que quieres crear una rama

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

Estoy bastante seguro de que esa característica no es compatible actualmente. Creo que su mejor opción es crear un archivo de texto descriptivo, un archivo README básicamente, en la rama que tenga la información que desea.

La respuesta seleccionada me parece exagerada. Me inclinaría a mantener un archivo de descripción por sucursal que es un archivo normal controlada por la fuente, por ejemplo master.txt, dev.txt, etc, y si hay un número difícil de manejar o ramas que crearía una jerarquía a una mejor organizarlo.

Solo usa:

git config branch.<branch name>.description

Para dar crédito donde se debe: https://glebbahmutov.com/blog/git-branches-with-descriptions/

Utilizar

git branch --list -v

para mostrar una rama aguas arriba:

git branch --list -vv

Agregar -rpara mostrar solo controles remotos o -apara mostrar controles remotos y locales.