Managing Your Local Project Repos

Git is great for managing a project. And Github is a great way to share your git managed project with your teammates and the world. But, how do you manage all of those projects locally? I'm not claiming this is the only way or even the best way. It's just my way of managing the repos I need to have locally. So let's get down to it.

Projects Namespace

I like to put all of the projects under a main projects folder. I use the name projects, but you could use whatever you like: workspace, repos, code, gits, etc...

  projects/

Pretty simple stuff. What's next?

Author/Project Folder Structure

Whenever I clone a repo I create a folder for the author or organization name that matches up with github then clone the project into that. An easy example would be projects under my account that were created by me. I don't put forked projects under my name, but I will get to that later.

  projects/
  └── nhessler/
      ├── converserver/
      └── hacknut-theme/

And I have projects at customink that I work on so let's add some of those projects in and see what things look like.

  projects/
  ├── customink/
  ¦    ├── fauxhai/
  ¦    ├── gigo/
  ¦    ├── secondbase/
  ¦    └── stoplight/
  └── nhessler/

This should be enough to see the basic structure of how I manage my projects. You can see that each project is located inside of a folder representing the originating author.

Local Projects

This works great for projects on github, but what about projects you have only on your machine? Well, you could put them under the account you plan to push them to. But, that breaks the convention of projects living under their author namespace. And, it makes it hard to remember what has and hasn't been pushed up under that account. So, until I've pushed a project to github I put them under the _local folder. The _ is added to make sure it's always at the top of the author list.

  projects/
  ├── _local/
  ¦    ├── dotfiles/
  ¦    └── blog/
  ├── customink/
  └── nhessler/

I know, I know. I really should get those pushed to github. but at least I can easily see that they aren't on github yet and resolve that issue quickly. The _local folder is also great for playing around with projects you don't ever plan to push github. You can write some code, play around with it, and delete later. when it is time to push it to github then you can move it under the appropriate folder.

Forked Projects

As I said earlier, I deal with forked libraries a bit differently. Let's look at a couple of those projects. Specifically, we'll look at oh-my-zsh by Robby Russel, prelude by Bozhidar Batsov, and monokai-emacs by Kelvin Smith. First, let's just see the directory structure for these projects.

  projects/
  ├── _local/
  ├── bbatsov/
  ¦   └── prelude/
  ├── customink/
  ├── nhessler/
  ├── oneKelvinSmith/
  ¦   └── monokai-emacs/
  └── robbyrussel/
      └── oh-my-zsh/

Note that each project is under the original author's name. Why do I do this? There are a couple reasons. First, I like to remember where the projects came from and this helps remind me who the original authors are. Second, project names are not unique. There are forks of projects, and there are projects with the same name that are completely different. Doing a search on github for rails turned up 138K repositories and on the first page 7 out of ten were named 'rails' the only difference was author name. the first two projects were 'rails/rails' and 'capistrano/rails'. Two projects I can easily see people forking. You could complain that maybe capistrano should have used the project name capistrano-rails over rails, but is it worth it? Finally, prelude and oh-my-zsh are libraries that were meant to be used by cloning them to your local machine, and I don't need or want to fork them to use them. I can just clone them from the original repo.

Final Thoughts

Here are some other things to think about that make this setup a little more useful.

If you use ZSH it would be helpful to add your projects folder to the CDPATH environment variable. I also add the nhessler and customink folders. This way I can jump to my frequently used projects by name only.

I also diverge a bit from how github recommends you fork and clone a repo. I still fork the repo, but I then clone the original and set up a remote called 'fork' which points at my fork of the repo. I find this matches how I think about forked projects better and seems to be in line with my folder structure as well.

If you have a workflow that you like to use for managing your repos that differs from, this I would love to hear about it.