Описания веток в Git
Есть ли способ в Git иметь "описание" для веток?
Хотя я пытаюсь использовать описательные имена, работа над одной веткой иногда ослабляет память о том, почему я создал некоторые другие ветки тем. Я пытаюсь использовать описательные имена для веток, но я думаю, что было бы неплохо "описание" (краткое примечание о назначении ветки).
16 ответов
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 alias, модифицирующий 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() {
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 == $(git rev-parse --abbrev-ref HEAD) ]; 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 предложенный Chris J может работать при условии, что он настроен с помощью специального драйвера слияния, определенного в .gitattribute,
Таким образом, локальная версия README всегда сохраняется во время слияний.
"Описание" для ветвей также известно как "комментарий", связанный с этими метаданными, и оно не поддерживается.
По крайней мере, с README файл, вы можете, для любой ветви, сделать:
$ git show myBranch:README
Если ваш README находится в корневом каталоге вашего REPO, он будет работать с любого пути, так как путь, используемый git show является абсолютным из верхнего каталога указанного репо.
Здесь есть два популярных предложения:
git branch --edit-description: Нам это не нравится, потому что ты не можешь это подтолкнуть. Может быть, я помню, что делают созданные мной ветки, но моя команда точно не может.READMEфайл pr. ветка. Это боль во время слияний: супер-склонны к конфликтам слияний, и мы будем втягиватьREADMEиз ветвей, когда мы объединяем функциональные ветви. Различия между ветвями - это тоже боль.
Мы решили создать сироту branches-readme ветка. Ветви-сироты - это ветви с собственной историей - вы можете знать их по Github's. gh-pages ветви. Эта сиротская ветвь содержит одну 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> в репозитории будет отображаться описание ветки, если установлено.
Вот gitalias это позволяет вам устанавливать и читать описания текущей ветки:
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
Отдельное спасибо @Felicio за ответ, с которого я начал.
Вот возможная реализация 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 branch branch-20200328
git notes add branch-20200328 -m "This branch is for whatever"
git notes show branch-20200328
Вы можете прикрепить комментарии к тегам:
git tag -m 'this was a very good commit' tag1
По договоренности у вас могут быть теги, связанные с именами веток, или вы можете использовать тег -f, чтобы оставить закомментированный тег в заголовке веток вашей темы.
Использование
git branch --list -v
показать ветку вверх по течению:
git branch --list -vv
добавлять -r показывать только пульты или -a показать удаленные и локальные.
Вы можете использовать
git config --get-regexp "branch.*.description"
Просто используйте:
git config branch.<branch name>.description
Чтобы получить кредит там, где он нужен: https://glebbahmutov.com/blog/git-branches-with-descriptions/
Что касается от 2012 года , Git 1.7.9 (Q1 2012) также включал некоторые проверки для:
См. (5 февраля 2012 г.) .
(Объединено в коммите d88698e , 10 февраля 2012 г.)
commit c2d17ba
branch --edit-description: защита от неправильного ввода имени ветки
Очень легко ошибиться в названии ветки при редактировании ее описания, например
$ git checkout -b my-topic master : work work work : now we are at a good point to switch working something else $ git checkout master : ah, let's write it down before we forget what we were doing $ git branch --edit-description my-tpoicКоманда не замечает, что ветки my-tpoic не существует.
Оно не теряется (становится описанием еще не родившейся мифологической ветви), но не очень полезно.
Так что обнаруживайте такой случай и устраняйте ошибки, чтобы уменьшить фактор горя от этой распространенной ошибки.Кстати, это также приводит к ошибке, когда HEAD указывает на нерожденную ветку (сразу после "
init", или "checkout --orphan"), потому что в этот момент у вас даже нет коммита, который является частью вашей истории, и нет смысла описывать, чем эта конкретная ветка отличается от ветки, от которой она разветвилась, что является полезной информацией, которую Описание ветки предназначено для захвата.Мы можем захотеть рассмотреть случай нерожденного ребенка позже, но это выходит за рамки этого патча, чтобы предотвратить более распространенные ошибки до того, как серия 1.7.9 получит слишком широкое распространение.
Хотя user893 от 2012 года точен, использование может привести к: ответаответ
fatal: could not unset 'branch.main.description'
" GIT_EDITOR=: git branch --edit-description( ) привел к ошибке, которая была исправлена в Git 2.39 (4 квартал 2022 г.).
См. (30 сентября 2022 г.) .
(Объединено в коммите 272be0d, 17 октября 2022 г.)
коммит e288b3d: не ошибиться
--edit-desc
Представьте, что вы бежите». " ( ) , находясь в ветке без описания ветки, а затем выйдите из редактора после очистки буфера редактирования, что является способом сообщить команде, что вы передумали и в конце концов вам не нужно описание.
Команда должна просто с радостью подчиниться, не добавляя описание ветки для текущей ветки, и успешно завершиться.
Но это не удается:$ git init -b main $ git commit --allow-empty -m commit $ GIT_EDITOR=: git branch --edit-description fatal: could not unset 'branch.main.description'Конечный результат в порядке, поскольку переменная конфигурации не существует в результирующем репозитории, но мы должны поступить лучше.
Если мы знаем, что у нас не было описания, и если редактор попросит нас не иметь описания, мы можем просто вернуться, ничего не делая.Это, конечно, представляет TOCTOU.
( Время проверки на время использования (TOCTOU): класс программных ошибок, вызванных состоянием гонки, включающим проверку состояния части системы (например, учетных данных безопасности) и использование результаты этой проверки.)
Если вы добавите описание ветки в ту же ветку из другого окна, в то время как у вас был открыт редактор для редактирования описания, а затем выйдете из редактора, ничего там не написав, в итоге мы не удалим описание, которое вы добавили в другом окне. .
Но в этот момент вы обманываете себя в своем собственном репозитории, и если это больно, вам лучше этого не делать ;-).
Также: " git branch --edit-description" ( ) в нерожденной ветке ошибочно сказал, что такой ветки не существует, что было исправлено с помощью Git 2.39 (4 квартал 2022 г.).
См. (8 октября 2022 г.) .
(Объединено в коммите 4050354, 17 октября 2022 г.)
коммит bcfc82b: описание ошибок несуществующей ветки
Подписал: Рубен Хусто
Когда в репозитории еще нет коммитов, некоторые ошибки описывают, что ветки нет:
$ git init -b first $ git branch --edit-description first error: No branch named 'first'. $ git branch --set-upstream-to=upstream fatal: branch 'first' does not exist $ git branch -c second error: refname refs/heads/first not found fatal: Branch copy failedЭта «первая» ветвь еще не рождена, но сказать, что ее не существует, сбивает с толку.
Опции «-c» (копировать) и «-m» (переименовать) показывают одну и ту же ошибку, когда исходная ветвь не существует:
$ git branch -c non-existent-branch second error: refname refs/heads/non-existent-branch not found fatal: Branch copy failed $ git branch -m non-existent-branch second error: refname refs/heads/non-existent-branch not found fatal: Branch rename failedОбратите внимание, что "
--edit-description" без явного аргумента уже учитывает пустое хранилище в своей ошибке.
Также обратите внимание, что "-m" на начальной ветке это разрешенная операция.Сделайте описания ошибок для операций с нерожденными или несуществующими ветвями более информативными.
Это результат изменения:
$ git init -b first $ git branch --edit-description first error: No commit on branch 'first' yet. $ git branch --set-upstream-to=upstream fatal: No commit on branch 'first' yet. $ git branch -c second fatal: No commit on branch 'first' yet. $ git branch [-c/-m] non-existent-branch second fatal: No branch named 'non-existent-branch'.
С Git 2.39 (4 кв. 2022 г.) " git branch --edit-description @{-1}" ( manmanmanman ) теперь является способом редактирования описания ветки, в которой вы были, прежде чем переключиться на текущую ветку.
См. (11 октября 2022 г.) Рубена Хусто ()Рубена Хусто (
rjusto) .
(Объединено Junio C Hamano ()Junio C Hamano --
gitster--Junio C Hamano -- --Junio C Hamano -- --Junio C Hamano ()Junio C Hamano -- -- в коммите c2058ea, 21 октября 2022 г.)
коммит 0dc4e5c
branch: поддержка ярлыков типа , завершенаПодписал: Рубен Хусто
Команда ветки с параметрами "edit-description", "set-upstream-to" и "unset-upstream" ожидает имя ветки.
Поскольку ae5a6c3 (checkout: осуществлять "@{-N}" имя ярлыка для N-й последней ветки, 2009-01-17, Git v1.6.2-rc0 -- merge), ветку можно указать с помощью ярлыков, таких как@{-1}.
Эти ярлыки должны быть разрешены при рассмотрении аргументов.Мы можем изменить описание ранее проверенной ветки с помощью:
$ git branch --edit--description @{-1}Мы можем изменить исходную часть ранее извлеченной ветки с помощью:
$ git branch --set-upstream-to upstream @{-1} $ git branch --unset-upstream @{-1}
Я уверен, что эта функция в настоящее время не поддерживается. Я думаю, что вам лучше всего создать текстовый файл описания, в основном README, в ветке, в которой есть нужная вам информация.
Выбранный ответ кажется мне излишним. Я был бы склонен поддерживать файл описания для каждой ветви, который является нормальным файлом, контролируемым источником, скажем master.txt, dev.txtи т. д. и если есть громоздкое число или ветви, я бы создал иерархию, чтобы лучше организовать ее.