Git - should I have a different README in each branch?

Question

I've just realised navigating in Bitbucket that it would be possible to have different READMEs in each branch, each one talking about the branch. Otherwhise, Bitbucket shows the master README for each branch, which doesn't have many sense.

Would it be a good practice?

Answer 1

The README is just another file under source control and thus, there is nothing special happening with that file from a Git perspective. Typically the README is supposed to give a high level overview of the project; how to install it, its dependencies, license, team member listing etc. This information is unlikely to change from branch to branch. For that reason, it makes sense for it to persist across all branches because even though the branch might be for a new feature, the high level details of the project are probably staying the same. Moreover, branches such as feature, hot fix, bug fix etc. are rather ephemeral in nature so once they're merged into develop or master they're usually (or at least should be) deleted. So I can't really see a reason for you needing to have a custom README for each branch.

So I guess the answer is "no", you shouldn't have a different README in each branch. So long as you're following a sensible branching model and tagging releases w/ notes when necessary you don't need to spend additional time writing up new README content for each branch.

Answer 2

No, it will not be a good practice.

While indeed the different branches have different purposes and description for each particular one could be useful, this is not the purpose of a README file. The information contained in a README file is intended to describe the whole project and not individual aspect or branch.

Usually a README file contains Synopsis, Motivation, Installation information, Code examples, Tests, API reference, Contributors section and License information. This information is generally not unique for each branch, since it focuses on the project as a whole.

In other words, a README file is used to inform another people(in most cases other developers) what the project is about, what is its purpose, how can you run it and other similar meta details.