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.