Описания веток в Git

Есть ли способ в Git иметь «описание» для веток?

Хотя я пытаюсь использовать описательные имена, работа над одной веткой иногда ослабляет память о том, почему я создал некоторые другие ветки тем. Я пытаюсь использовать описательные имена для веток, но я думаю, что «описание» (краткое примечание о назначении ветки) было бы неплохо.

Git 1.7.9 поддерживает это. Из примечаний к выпуску 1.7.9 :

 * "git branch --edit-description" может использоваться для добавления описательного текста
   объяснить, о чем ветка темы.

Вы можете увидеть эту функцию, представленную еще в сентябре 2011 года, с коммитами 6f9a332 , 739453a3 , b7200e8 :

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

--edit-description::

Откройте редактор и отредактируйте текст, чтобы объяснить, для чего предназначена ветка, которая будет использоваться различными другими командами (например request-pull).

Обратите внимание, что это не будет работать для отдельной ветки HEAD.

Это описание используется сценарием request-pull: см. Commit c016814783 , но также git merge --log.

request-pull является сценарием, используемым для суммирования изменений между двумя коммитами в стандартный вывод, и включает указанный URL в сгенерированную сводку.

[От @AchalDave] К сожалению, вы не можете отправить описания, поскольку они хранятся в вашей конфигурации, что делает их бесполезными для документирования веток в команде.

Если же в конечном итоге с помощью README, создайте GIT псевдоним модифицирующий , git checkoutчтобы ваш README отображается каждый раз , когда вы переключаете ветки.

Например, добавьте это в ~ / .gitconfig под [alias]

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

После этого вы можете запустить git cor <branch_name>переключение ветви и отобразить README ветви, на которую вы переключаетесь.

Используйте git branch --edit-descriptionдля установки или редактирования описания ветки.

Вот функция оболочки для отображения веток, похожих на, git branchно с добавленными описаниями.

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

Вот как gbвыглядит текст, показанный здесь в случае, если изображение гниет:

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

И как изображение, чтобы вы могли видеть цвета:

READMEПредложил Крис J может работать, при условии , что установка с драйвером пользовательского объединения , определенным в.gitattribute .
Таким образом, локальная версия READMEвсегда сохраняется во время слияний.

«Описание» для ветвей также известно как «комментарий», связанный с этими метаданными, и оно не поддерживается.

По крайней мере, с READMEфайлом вы можете, для любой ветви, сделать:

$ git show myBranch:README

Если ваш README находится в корневом каталоге вашего РЕПО, он будет работать с любого пути, поскольку используемый путь git showявляется абсолютным из верхнего каталога указанного репо.

Здесь есть два популярных предложения:

1. git branch --edit-description: Нам это не нравится, потому что ты не можешь это подтолкнуть. Может быть, я помню, что делают созданные мной ветки, но моя команда точно не может.
2. READMEфайл pr. филиал. Это проблема при слияниях: супер-склонна к конфликтам слияний, и мы будем извлекать READMEиз ветвей, когда мы объединяем функциональные ветви. Различия между ветвями - это тоже боль.

Мы решили создать сиротскую branches-readmeветвь. Ветви-сироты - это ветви с собственной историей - вы можете знать их по gh-pagesветкам Github . Эта сиротская ветвь содержит один READMEфайл. У этого есть содержание как:

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

Это толкаемый и дружественный к слиянию. Просмотр READMEиз любой ветки с:

git show branches-readme:README

Недостатки в том, что вам нужно оформить странную сиротскую ветку, когда вы хотите обновить, READMEа READMEона не обновляется автоматически, когда ветви переименовываются, приходят или уходят. Это хорошо для нас, хотя.

Сделай это как:

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

Аналогично, отдельные члены команды могут также создавать свои собственные branches-$userсиротские ветви, описывающие их собственные частные ветви, если они хотят, если они не подталкивают их к команде.

При дальнейшей комплектации это также может быть интегрировано с выводом git branch. С этой целью, возможно, README.yamlфайл может рассматриваться вместо простой README.

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

Команда определит глобальную опцию alias.aboutкак выражение оболочки. Запуск git about <branch>в репозитории покажет описание ветки, если установлено.

Вот возможная реализация команды, на git branchesкоторую ссылается Грег Хьюгилл:

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

Вот git aliasчто позволяет вам устанавливать и читать описания текущей ветки:

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

Использование / примеры:

(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

Отдельное спасибо @Felicio за ответ, с которого я начал.

Вы можете прикрепить комментарии к тегам:

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

По договоренности у вас могут быть теги, связанные с именами веток, или вы можете использовать тег -f, чтобы оставить закомментированный тег в заголовке веток вашей темы.

Скажем, вы хотите создать ветку

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

Я уверен, что эта функция в настоящее время не поддерживается. Я думаю, что вам лучше всего создать текстовый файл описания, в основном README, в ветке, в которой есть нужная вам информация.

Выбранный ответ кажется мне излишним. Я был бы склонен поддерживать файл описания для каждой ветви, который является нормальным, контролируемым источником файлом, скажем master.txt, dev.txtи т. Д., И если бы было громоздкое число или ветви, я бы создал иерархию, чтобы лучше организовать ее.

Просто используйте:

git config branch.<branch name>.description

Чтобы получить кредит там, где он требуется: https://glebbahmutov.com/blog/git-branches-with-description/

использование

git branch --list -v

показать ветку вверх по течению:

git branch --list -vv

Добавить, -rчтобы показать только пульты или -aпоказать удаленные и локальные.