GitHub – How to Use GitHub Organizations for a Project Spanning Multiple Repositories?

gitgithuborganizationrepository

I've started a project that involves at least three repositories on GitHub.

One of the repositories is a generic documentation-and-examples dump, and the other two contain the implementation of two programs that form the backbone of the project.

Should I use a GitHub Organization to handle such a configuration?
Or should I just dump it all to my own account, along with a dozen other, completely unrelated repositories?

Best Answer

Short answer ...

Start out with the repositories in your personal account. From there, if/when things grow and/or get popular with the community, move them to an organization account.

Long answer ...

Let's look at some of your options:

1. Organization:

For more information on GitHub Organization features, be sure to read:

GitHub Blog: Introducing Organizations

If you've ever had to manage multiple GitHub accounts, desired a company-specific dashboard, wanted to add read-only collaborators, or needed to give someone else administrative control over one of your repositories, you're going to love Organizations.

Based on your question, I can't say if an Organization is right for you (my gut is telling me "no"), but maybe looking at some real world examples will help you make your decision.

Here are some examples of GitHub Organizations that I find interesting to look at:

  1. https://github.com/gruntjs
    This is one of my favorite examples of an open source Organization account. I'm mostly impressed by the naming conventions used for repositories (i.e., essentially grunt/ is the main repo and all related core/contrib code/plugins/tasks live in grunt-xxxx/ repositories).

  2. https://github.com/github
    Probably it's worth looking at GitHub's own Org. account. The naming conventions used for the repositories aren't as tight as Grunt's (IMHO), but it's a good example nonetheless. Oh, and now's probably a decent time to point out the "Members" tab, as you don't get this for personal accounts or repositories.

  3. https://github.com/twbs
    Twitter Bootstrap. I think this is a good example of an Org. account with only a few repositories (note the single repo with 58,000+ stars). Also note that Bootstrap has five members (at the time of writing this), yet those five are responsible for an insanely popular repository (contrast that to the 214 members of the GitHub Organization).

    1. https://github.com/twitter: Twitter's main GitHub account.

A few more general examples:

  1. https://github.com/yeoman: Build tools.

  2. https://github.com/h5bp: HTML5 boilerplate.

  3. https://github.com/nprapps: News industry example.

2. Personal account

As you've mentioned already, you could create repositories inside your personal account and go from there.

Will you need collaborators?

GitHub Help: Collaborating / How do I add a collaborator?

As you can see, adding collaborators is pretty painless.

Based on your question, this option sounds like the one you want.

3. Repo with multiple branches:

You could create one repository and utilize branches to organize your related bits of code.

I don't think most folks would agree that this is the best way to organize your code:

On the other hand, there's nothing that says you can't organize related bits of code using branches.

One personal annoyance I have with this technique is that GitHub's GUI/interface will show you this message:

enter image description here

... when viewing branches other than your master (that is, if your branch is ahead/behind in commits).

Tip: If you're using a more recent version of Git, you can pull specific branches using git clone -b mybranch --single-branch git://sub.domain.com/repo.git:

Related:

4. Hybrid approach:

Should I use a GitHub Organization to handle such a configuration? Or should I just dump it all to my own account, along with a dozen other, completely unrelated repositories?

You could use a combination of all of the above. For example:

  1. Setup an Organization for "... generic documentation-and-examples dump, and the other two contain the implementation of two programs that form the backbone of the project".

  2. Use your personal account for "... a dozen other, completely unrelated repositories"

  3. Use branches for demo pages gh-pages, related code and/or documentation.

Note(s):

It's also worth mentioning that you can use a repository's WIKI for documentation purposes:

Related Topic