Special files

In git there are some files which have some importance, either on your remote repository or just in general.

Here are some examples

README

File location README.md

When creating a repository on GitHub or GitLab, it will ask if you want to initialise it with a README. This is a file written in markdown, which just contains a description of what the project is.

If you visit a project e.g. this wiki, you will see a description rendered below all the files. This is the README, which both GitLab and GitHub will render on the home directory of your project.

LICENSE

File location LICENSE or NOTICE

This stores the license of the project, telling people how they are allowed to use it. There are multiple difference licenses, as shown by GitHub’s documentation.

For our projects, we recommend to use the MIT license, which is as follows:

MIT License

Copyright (c) 2023 Your Name

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

This basically states that anyone can use this project for anything, but we don’t hold responsibility for any of the consequences.

For personal projects, you may want to find a license that fits your needs a bit better.

Note

When using licenses, it may have unintended consequences as you have to check if all the projects you are using has a compatible license with yours.

Gitignore

File location: .gitignore

This file stores a list of files or folders which should never be included in your git commits.

These will usually include caching files or output directories which should be generated by the developer on their local machine.

An example for a project using yarn and npm is:

# build output
dist/

node_modules
.yarn
!.yarn/releases
!.yarn/plugins
.pnp.*

.vscode
!.vscode/extensions.json
!.vscode/launch.json

# logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*


# environment variables
.env
.env.production

# macOS-specific files
.DS_Store

But these will vary depending on the tools and language you are using in a given project.

Templates are available online or you can use generate a gitignore specific to your development setup.

Gitmodules

File location .gitmodules

In most cases, this is not required and so will not be in a repository, this is a special file which is normally autogenerated by the submodule command in git (and so probably shouldn’t be edited manually).

But this stores all the locations and repos of the submodules you have added.

GitLab CI

File location .gitlab-ci.yml

This file controls the pipelines on the project see here for more information

MR/Issue Templates

File location .gitlab/merge_request_templates/*.md and .gitlab/issue_templates/*.md.

This is better explained here