Should I use branches for example uses of a github repo?

Question

I'm working on a Github repo called Designemplate at https://github.com/benwatkinsart/Designemplate and was thinking of developing some example uses of the CSS file to show how it's used. Should I use a branch called examples and store them there?

Answer 1

Using branches for this is possible, but extremely awkward to use. I recommend using branches only for different stages of development, e.g. as suggested by the git-flow model.

When can branches get awkward? Always then when two branches represent different resources (not just different versions of the same resource), so that you might want to view both resources at the same time. As you can only have one branch checked out in your working directory, you'll either end up switching back and forth between branches, or cloning the repo into a second directory to have another branch checked out there – starting another repo just for the second resource would have been much easier.

Instead, just create an examples/ directory. It's the simplest, most intuitive solution to your problem.

I also notice that your repo is using the GitHub Pages feature, where your repo is accessible as a website (here https://benwatkinsart.github.io/Designemplate/). It would make sense to make your examples accessible via this website, and simply add a link from each example to the corresponding source on GitHub. The Pages features only displays items on the gh-pages branch, not from any other branches.

• jb510: While I agree with the above, the other option would be to use a fork. I don't think it's a viable solution for you so I'm not proposing it as an answer. In no case would I use a branch, branches should really have a start (branch) and an end (eventual merge).
• amon: @jb510 I actually covered the possibility of a fork, but worded it as "cloning the repo" (which is what clicking the fork button in the GitHub interface effectively does). The two clones can have independent history, but also view each others branches when set up as "remotes". So we'd still be kinda using branches after all.

Answer 2

No use directories for different content.

Use branches for content that is changing or being changed over time rather than using it to segregate types types of content.

Another option (if you don't want all those files in your base source control repository)... is to create a separate repository and then include that in the other one. For example in rails you would make a gem, publish it and then refer to it in the Gemfile as a dependency. You don't mention rails so your exact process may vary.

Another option is to have a top level directory for the project, to have directories for the templates and also a code directory, within which the .git repo resides.