Organizing A Git Repo

A very brief overview of various methods you can use to organize a git repo.

Adding README.md's

README files are great. README.md files are even better. MD stands for MarkDown. MarkDown offers an easy way to add styling to your standard README file.

Take a look at the Basic Syntax for a starting point.

In fact, this page is written with markdown if you want to see the raw version try clicking here.

The great thing is that on most sites like github a README, README.md, README.txt, etc will be displayed directly in the site. The .md version does all of the proper styling which can make your documentation readable and good looking.

Where To Place README.md Files

Base Of The Repo

This one is a 100% must. This should describe what the repo is. An overview of where to find things. If the repo is a single project it should probably have instructions on how to build it.

First Level of Subdirectories

You will definitely want to do this if your repo has 2 or more independent projects/components in it. The base README.md would tell you what folders existed off of root and what was in them but these README.md files would give much more detail about what the component is or how to use it.

Example Layout

Single Project Repo

The 'src' and 'tests' folders are just examples but not required.

/README.md    - How to build and use the project.
/src/...      - Just an example of where you might store source files.
/tests/...    - Just an example of where you might store test files.
/python/      - If your single project uses multiple languages you may
                choose to separate the files into language specific folders.
/lib/         - If your single project is in one language you might just
                want your root of your repo to be the entry point for everything.

Multiple Project/Component Repo

/README.md                    - Explains what you will find in /selenium-intro/ and /some_other_project/
/selenium-intro/README.md     - Detailed explanation of what this is. Instructions on using it.
/selenium-intro/tests/...     - All of the sub folders related to this project.
/some_other_project/README.md - Detailed explanation of what this is. Instructions on using it.
/some_other_project/tests/... - All of the sub folders related to this project.

Git Ignore

If your project is going to create some temporary files while you use it and you don't want those to show up as uncommitted files you can add them to a file called .gitignore

This file contains one file or file glob per line (glob being *.exe rather than program.exe)

These can be in individual directories but it is frequently easier to just maintain the ignores from the very top of the repo.

Example

/.gitignore

Would contain something like...

src/*.o
src/temp/*
src/Makefile

© 2024 - Zolan's Primary Personality