Branch descriptions in Git

If you do end up using the README, create a git alias modifying git checkout so that your README is displayed every time you switch branches.

For example, add this in ~/.gitconfig, under [alias]

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

After this, you can run git cor <branch_name> to switch branch and display the README of the branch you're switching to.

Git 1.7.9 supports this. From the 1.7.9 release notes:

 * "git branch --edit-description" can be used to add descriptive text
   to explain what a topic branch is about.

You can see that feature introduced back in September 2011, with commits 6f9a332, 739453a3, b7200e8:

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

--edit-description::

Open an editor and edit the text to explain what the branch is for, to be used by various other commands (e.g. request-pull).

Note that it won't work for a detached HEAD branch.

That description is used by the script request-pull: see commit c016814783, but also git merge --log.

request-pull is a script used to summarizes the changes between two commits to the standard output, and includes the given URL in the generated summary.

[From @AchalDave] Unfortunately, you can't push descriptions since they're stored in your config, making it useless for the sake of documenting branches in a team.