Deskripsi cabang di Git

Apakah ada cara di Git untuk memiliki 'deskripsi' untuk cabang?

Sementara saya mencoba menggunakan nama deskriptif, bekerja sebentar di satu cabang terkadang mengurangi ingatan saya mengapa saya membuat beberapa cabang topik lainnya. Saya mencoba menggunakan nama deskriptif untuk cabang, tapi saya pikir 'deskripsi' (catatan singkat tentang tujuan cabang) akan menyenangkan.

Git 1.7.9 mendukung ini. Dari catatan rilis 1.7.9 :

 * "git branch --edit-description" dapat digunakan untuk menambahkan teks deskriptif
   untuk menjelaskan tentang apa topik cabang.

Anda dapat melihat fitur yang diperkenalkan kembali pada September 2011, dengan komit 6f9a332 , 739453a3 , b7200e8 :

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

--edit-description::

Buka editor dan edit teks untuk menjelaskan untuk apa cabang, untuk digunakan oleh berbagai perintah lain (misalnya request-pull).

Perhatikan bahwa ini tidak akan berfungsi untuk cabang HEAD yang terpisah.

Uraian itu digunakan oleh tarikan permintaan skrip: lihat commit c016814783 , tetapi juga git merge --log.

request-pull adalah skrip yang digunakan untuk merangkum perubahan antara dua commit ke output standar, dan menyertakan URL yang diberikan dalam ringkasan yang dihasilkan.

[Dari @AchalDave] Sayangnya, Anda tidak dapat mendorong deskripsi karena disimpan di konfigurasi Anda, menjadikannya tidak berguna demi mendokumentasikan cabang dalam tim.

Jika Anda tidak berakhir dengan menggunakan README, membuat git alias memodifikasi git checkoutsehingga README Anda ditampilkan setiap kali Anda beralih cabang.

Sebagai contoh, tambahkan ini di ~ / .gitconfig, di bawah [alias]

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

Setelah ini, Anda dapat menjalankan git cor <branch_name>untuk beralih cabang dan menampilkan README dari cabang yang Anda pindah.

Menggunakan git branch --edit-description untuk mengatur atau mengedit deskripsi cabang.

Berikut adalah fungsi shell untuk menampilkan cabang yang mirip git branchtetapi dengan deskripsi yang ditambahkan.

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

Berikut ini gbtampilannya, ditampilkan di sini sebagai teks jika gambar membusuk:

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

Dan sebagai gambar, sehingga Anda dapat melihat warna:

The READMEdisarankan oleh Chris J dapat bekerja, asalkan itu adalah setup dengan sopir merge kustom didefinisikan dalam.gitattribute .
Dengan begitu, versi lokalREADME selalu dipertahankan selama penggabungan.

"Deskripsi" untuk cabang juga dikenal sebagai "komentar" yang terkait dengan data meta itu, dan itu tidak didukung.

Setidaknya, dengan READMEfile, Anda dapat, untuk cabang apa pun, melakukan:

$ git show myBranch:README

Jika README Anda berada di direktori root REPO Anda, itu akan bekerja dari jalur apa pun, karena jalur yang digunakan oleh git showadalah mutlak dari direktori teratas dari repo tersebut.

Ada dua saran populer di sini:

1. git branch --edit-description: Kami tidak suka ini karena Anda tidak bisa mendorongnya. Mungkin saya bisa mengingat apa yang dilakukan cabang-cabang yang saya buat, tetapi tim saya pasti tidak bisa.
2. READMEfile pr. cabang. Ini menyusahkan selama penggabungan: Sangat rentan untuk menggabungkan konflik dan kami akan menarik READMEdari cabang ketika kami menggabungkan cabang fitur. Perbedaan antar cabang juga menyebalkan.

Kami telah memutuskan untuk membuat branches-readmecabang yatim . Cabang-cabang yatim adalah cabang-cabang dengan sejarah mereka sendiri yang terpisah - Anda mungkin mengenal mereka dari gh-pagescabang - cabang Github . Cabang yatim ini berisi satu READMEfile. Ini memiliki konten seperti:

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

Ini push-mampu dan ramah-gabung. Lihat READMEdari cabang mana saja dengan:

git show branches-readme:README

Kerugiannya adalah Anda harus checkout cabang yatim aneh ketika Anda ingin memperbarui READMEdan READMEtidak memperbarui secara otomatis ketika cabang diganti nama, datang atau pergi. Tapi itu baik untuk kita.

Lakukan seperti:

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

Serupa, anggota tim individu juga dapat membuat branches-$usercabang yatim mereka sendiri menggambarkan cabang pribadi mereka jika mereka mau, selama mereka tidak mendorong mereka ke tim.

Dengan tooling lebih lanjut, ini juga dapat diintegrasikan dengan output git branch. Untuk itu, mungkin sebuah README.yamlfile dapat dianggap sebagai ganti file biasa README.

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

Perintah akan menentukan opsi global alias.aboutsebagai ekspresi shell. Berjalan git about <branch>di repositori akan menampilkan deskripsi cabang jika disetel.

Berikut adalah kemungkinan implementasi dari git branchesperintah yang disinggung oleh Greg Hewgill:

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

Inilah git aliasyang memungkinkan Anda mengatur dan membaca deskripsi di cabang saat ini:

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

Penggunaan / contoh:

(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

Terima kasih khusus kepada @Felicio untuk jawaban yang membuat saya mulai.

Anda dapat melampirkan komentar ke tag:

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

Secara konvensi, Anda dapat memiliki tag yang terkait dengan nama cabang Anda atau Anda dapat menggunakan tag -f untuk menyimpan tag komentar di kepala cabang topik Anda.

Katakanlah Anda ingin membuat cabang

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

Saya cukup yakin bahwa fitur saat ini tidak didukung. Saya pikir taruhan terbaik Anda adalah membuat file teks deskripsi, README pada dasarnya, di cabang yang memiliki informasi yang Anda inginkan.

Jawaban yang dipilih sepertinya berlebihan bagi saya. Aku akan cenderung untuk mempertahankan file deskripsi per cabang yang merupakan sumber dikendalikan file normal, katakanlah master.txt, dev.txt, dll dan jika ada nomor atau cabang berat saya akan membuat hirarki untuk lebih mengatur itu.

Cukup gunakan:

git config branch.<branch name>.description

Untuk memberikan kredit saat kredit jatuh tempo: https://glebbahmutov.com/blog/git-branches-with-description/

Menggunakan

git branch --list -v

untuk menampilkan cabang hulu:

git branch --list -vv

Tambahkan -runtuk menampilkan hanya remote atau -auntuk menunjukkan remote dan lokal.