357

In GitHub, what is the conceptual difference between a project (that can be created inside a repository) and a repository?

I've seen several similar questions (here, here and here) in SO, but none of them explains what is a GitHub project, what is a GitHub repository and when to use each one of them.

I would appreciate if someone can explain each term, and provide an example of when to use/create each one. For instance, if I have several prototype applications, all independent of each other, what do I create in order to manage in an organized way the source code for all of them?

Community
  • 1
  • 1
carlossierra
  • 4,479
  • 4
  • 19
  • 30
  • 3
    A github repository is just a "directory" where files and folders can exist. Other people can create their own copies of this "directory" and modify it as they wish, then request that their changes get put into the main repository. As for projects, I'm not sure since I've never used them. – byxor Nov 09 '16 at 14:55
  • 2
    You said you have seen similar question, but have you actually read your first link? "That is a gitorious, not a git thing. You can have multiple repositories per project." and another answer on that same thread "Git has no such things as projects, only repositories.". If you indeed actually meant github projects I would suggest to check out the github docs about it https://help.github.com/articles/tracking-the-progress-of-your-work-with-projects/ – PeeHaa Nov 09 '16 at 15:11
  • 10
    @PeeHaa yes I did. The very first sentence states this: **"That is a gitorious, not a git thing. You can have multiple repositories per project.".** To me, this talks about Gitorius, not GitHub. Also, it says that in Gitorious you can have multiple repositories per project, but in GitHub is the other way around. So, I would really appreciate if you could explain how is this answering my question? – carlossierra Nov 09 '16 at 15:20
  • @PeeHaa also, please read carefully my question: I am talking about GitHub, not Git! – carlossierra Nov 09 '16 at 15:21
  • 7
    It's unfair to see how people can be so quick to downvote, but not take the time to read and digest what's been asked! – carlossierra Nov 09 '16 at 15:23
  • 2
    I think this touches on semantics where the new feature Projects - the visual board - conflicts with the overloaded usage of the term Project. The down vote is likely that this is not a programming question. – osowskit Nov 09 '16 at 19:26
  • Thanks @osowskit. I think this is the difference If you would care to post this as an answer and explain the use of the Projects feature, I would award you the correct answer. – carlossierra Nov 10 '16 at 14:04
  • 3
    This should have everything you need https://github.com/blog/2256-a-whole-new-github-universe-announcing-new-tools-forums-and-features#manage-your-ideas-with-projects – osowskit Nov 14 '16 at 04:36
  • Thanks @osowskit. Yes, that's the answer I was looking for. If you want, post it as an answer and I'll award the checkmark to you... – carlossierra Nov 14 '16 at 21:42
  • 1
    In a certain way it would make more sense to me if one project could have multiple repositories. I'm under the impression that GitHub noticed that is getting old and instead of doing a complete redesign just opted to make a workaround and sell it as a good thing. By the way, who is the owner of GitHub right now? Maybe the answer gives some clue about why this is happening. Just thinking out loud. – Almir Campos May 24 '20 at 23:29

7 Answers7

268

Fact 1: Projects and Repositories were always synonyms on GitHub.

Fact 2: This is no longer the case.

There is a lot of confusion about Repositories and Projects. In the past both terms were used pretty much interchangeably by the users and the GitHub's very own documentation. This is reflected by some of the answers and comments here that explain the subtle differences between those terms and when the one was preferred over the other. The difference were always subtle, e.g. like the issue tracker being part of the project but not part of the repository which might be thought of as a strictly git thing etc.

Not any more.

Currently repos and projects refer to a different kinds of entities that have separate APIs:

Since then it is no longer correct to call the repo a project or vice versa. Note that it is often confused in the official documentation and it is unfortunate that a term that was already widely used has been chosen as the name of the new entity but this is the case and we have to live with that.

The consequence is that repos and projects are usually confused and every time you read about GitHub projects you have to wonder if it's really about the projects or about repos. Had they chosen some other name or an abbreviation like "proj" then we could know that what is discussed is the new type of entity, a precise object with concrete properties, or a general speaking repo-like projectish kind of thingy.

The term that is usually unambiguous is "project board".

What can we learn from the API

The first endpoint in the documentation of the Projects API:

is described as: List repository projects. It means that a repository can have many projects. So those two cannot mean the same thing. It includes Response if projects are disabled:

{
  "message": "Projects are disabled for this repo",
  "documentation_url": "https://developer.github.com/v3"
}

which means that some repos can have projects disabled. Again, those cannot be the same thing when a repo can have projects disabled.

There are some other interesting endpoints:

  • Create a repository project - POST /repos/:owner/:repo/projects
  • Create an organization project - POST /orgs/:org/projects

but there is no:

  • Create a user's project - POST /users/:user/projects

Which leads us to another difference:

1. Repositories can belong to users or organizations
2. Projects can belong to repositories or organizations

or, more importantly:

1. Projects can belong to repositories but not the other way around
2. Projects can belong to organizations but not to users
3. Repositories can belong to organizations and to users

See also:

I know it's confusing. I tried to explain it as precisely as I could.

rsp
  • 107,747
  • 29
  • 201
  • 177
  • 6
    In Atlassian's Bitbucket, you can create projects which encompass a family of related repos. Does Github have this organizational feature? I had expected Github Projects to be that thing, but it clearly isn't. I can't seem to figure out how to make this organization possible in Github. I am *very* used to Bitbucket, so it may just be a learning curve. – Ungeheuer May 16 '20 at 19:48
  • 3
    In a certain way it would make more sense to me if one project could have multiple repositories. I'm under the impression that GitHub noticed that is getting old and instead of doing a complete redesign just opted to make a workaround and sell it as a good thing. By the way, who is the owner of GitHub right now? Maybe the answer gives some clue about why this is happening. Just thinking out loud. – Almir Campos May 24 '20 at 23:31
  • 6
    I came to this SO question assuming that repos are created inside projects, and not in the reverse. Now I'm totally confused. I mean, if you develop a new OS, can't you make the repos of the kernel, compiler, utils, etc belong to a "master project" which is the OS? Are you supposed to create an organisation account if you want to do things like this, so that the "organisation" is actually the "master project"? I don't get it. – cesss Jul 20 '21 at 09:51
  • but @rsp I can see on github link for create user project https://docs.github.com/en/rest/projects/projects#create-a-user-project. – Hemendr Jun 20 '22 at 10:22
  • There's also some complexity with "Teams" and "Issues" and "Drafts." Correct me if I'm wrong, but a Team can belong to an Organization. A Repository can belong to a Team. A User can belong to a Team. A (sub)Team can belong to a Team. Also, unlike with how Projects cannot belong to Users, a Project _can_ belong to a Team. Additionally, an Issue can belong to a Repository or a Project, and a Draft can belong to a Project (but not a Repository), though it can be converted to an Issue. Missing anything else? – M. Thompson Dec 21 '22 at 22:11
179

GitHub recently introduced a new feature called Projects. This provides a visual board that is typical of many Project Management tools:

Project

A Repository as documented on GitHub:

A repository is the most basic element of GitHub. They're easiest to imagine as a project's folder. A repository contains all of the project files (including documentation), and stores each file's revision history. Repositories can have multiple collaborators and can be either public or private.

A Project as documented on GitHub:

Project boards on GitHub help you organize and prioritize your work. You can create project boards for specific feature work, comprehensive roadmaps, or even release checklists. With project boards, you have the flexibility to create customized workflows that suit your needs.

Part of the confusion is that the new feature, Projects, conflicts with the overloaded usage of the term project in the documentation above.

osowskit
  • 5,904
  • 2
  • 29
  • 38
  • 1
    So I'm using Github to store the code for my individual research projects A, B, C, etc. If I am understanding it correctly, each research project would get it's own repository? So A gets a repository, B gets a repository, C gets a repository, etc.? – Plinth Apr 19 '18 at 01:59
  • When you fork a Repository, does your fork have access to the snapshot of the Project board? – geominded May 12 '18 at 05:37
  • 42
    how is this chosen as an accepted answer? simply copy paste of what is described. it can be read by the OP but people want to know with simple examples. – Emil Sep 13 '19 at 13:38
29

GitHub Repositories are used to store all the files, folders and other resources which you care about.

Git Project : It is also one of the Resource in Git Repository and main use of it is to manage the projects with a visual board. If you create a project in Git Repository it create a visual board like a Kanban board to manage the project.

In this way, you can have multiple projects in a repository.

Alexander Farber
  • 21,519
  • 75
  • 241
  • 416
Digamber
  • 291
  • 3
  • 2
10

In general, on GitHub, 1 repository = 1 project. For example: https://github.com/spring-projects/spring-boot . But it isn't a hard rule.

1 repository = many projects. For example: https://github.com/donhuvy/java_examples

1 projects = many repositories. For example: https://github.com/zendframework/zendframework (1 project named Zend Framework 3 has 61 + 1 = 62 repositories, don't believe? let count Zend Frameworks' modules + main repository)

I totally agree with @Brandon Ibbotson's comment:

A GitHub repository is just a "directory" where folders and files can exist.

Community
  • 1
  • 1
Vy Do
  • 46,709
  • 59
  • 215
  • 313
  • Thanks for your response. But I don't think your definition of a project is what GitHub calls a project, since the examples of multiple-project-repositories don't show anything in the Projects tab for those repositories. Can you please elaborate on this? – carlossierra Nov 09 '16 at 15:46
  • 4
    Actually, the example using Zend Framework is totally wrong! According to GitHub's nomenclature, there's an organisation named "zendframework" which owns many repositories, including one also named "zendframework" and one for each module of the framework. – igorcadelima Mar 17 '17 at 18:33
  • 3
    9 Nov. 2017: the example of **1 repository = many projects** returns a 404. – Bram Vanroy Nov 09 '17 at 09:25
  • 1
    links are broken – Peyman Mohamadpour Mar 29 '19 at 21:26
  • 3
    In terms of GitHub, this answer is conflicting other more popular answers above. – Manohar Reddy Poreddy Sep 14 '19 at 03:42
7

The conceptual difference in my understanding it that

  • A project can contain many repo's and that are independent of each other, while simultaneously a repo may contain many projects.
  • Repository being just a storage place for code while a project can be a collection of tasks for a certain feature.

Does that make sense? A large repo can have many projects being worked on by different people at the same time (lots of difference features being added to a monolith), a large project may have many small repos that are separate but part of the same project that interact with each other - microservices? Its a personal take on what you want to do.

I think that repo (storage) vs project (tasks) is the main difference - if i am wrong please let me know / explain! Thanks.

Jeremy
  • 1,170
  • 9
  • 26
2

Reading the responses to this question leads me to the conclusion that the two terms are interchangeable and no-one has actually managed to distinguish between the two in a clearly understandable way!

lecoxsportif
  • 29
  • 1
  • Please provide additional details in your answer. As it's currently written, it's hard to understand your solution. – Community Aug 27 '21 at 17:19
  • This is just incorrect. Projects and Repositories are not at all interchangable terms on Github. – madacoda Apr 24 '23 at 20:57
  • @madacoda then please do feel free to post an answer and make a clear response in your words. – Andrew S Aug 09 '23 at 17:16
1

This is my personal understanding about the topic.

For a project, we can do the version control by different repositories. And for a repository, it can manage a whole project or part of projects.

Regarding on your project (several prototype applications which are independent of each them). You can manage the project by one repository or by several repositories, the difference:

  1. Manage by one repository. If one of the applications is changed, the whole project (all the applications) will be committed to a new version.

  2. Manage by several repositories. If one application is changed, it will only affect the repository which manages the application. Version for other repositories was not changed.

lake
  • 112
  • 4