A collection of GitHub repo files with brief explinations and links to deeper learnings.
- Read through the Special Files section to discover each of their uses.
- Investigate links in the Resources are to discover additional details.
- Copy/paste from the examples if needed.
- If you find this repo interesting ⭐ it for future reference.
Are all these files necessary?
Nope. Just use what you need.
When should I name the file ending in .md?
Whenever you want the file to be visually rendered using Markdown features like headings, sections, lists, code example syntax coloring, clickable links, bold, italic, ... you should use .md.
Why are filenames in all caps?
To avoid confusion with other files and to make them more noticeable as a "special" file.
├── .github │ ├── FUNDING.yml │ ├── ISSUE_TEMPLATE │ │ ├── bug_report.md │ │ ├── config.yml │ │ └── feature_request.md │ └── PULL_REQUEST_TEMPLATE.md ├── .gitignore ├── .nojekyll ├── ACKNOWLEDGMENTS.md ├── CHANGELOG.md ├── CITATION.cff ├── CODEOWNERS ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── CONTRIBUTORS.md ├── LICENSE ├── README.md ├── SECURITY.md ├── SUPPORT.md └── UPGRADING.md
- .gitignore
- .nojekyll
- ACKNOWLEDGMENTS.md
- CHANGELOG.md
- CITATION.cff
- CODEOWNERS
- CODE_OF_CONDUCT.md
- gitigCONTRIBUTINGnore.md
- CONTRIBUTORS.md
- ISSUE_TEMPLATE.md
- LICENSE
- README.md
- SECURITY.md
- SUPPORT.md
- UPGRADING.md
- .github/FUNDING.yml
- .github/ISSUE_TEMPLATE/bug_report.md
- .github/ISSUE_TEMPLATE/feature_request.md
- .github/PULL_REQUEST_TEMPLATE.md
- .github/ISSUE_TEMPLATE/config.yml
This file is used to tell Git which files and folders to ignore.
Typical files and directories to ignore are:
-
System files like
.DS_Store -
Generated files such as
dist/andnode_modules/ -
Files containing API keys, passwords, secrets or other sensitive information
-
Log files in a directory such as
logs/ -
Files that are not part of the project
-
Files that you don't want to share
You can add a .gitignore file in your repository's root directory or any other folder to tell Git which files and directories to ignore when you make a commit. To share the ignore rules with other users who clone the repository, commit the
.gitignorefile in to your repository.GitHub maintains an official list of recommended
.gitignorefiles for many popular operating systems, environments, and languages in the github/gitignore public repository. You can also use gitignore.io to create a .gitignore file for your operating system, programming language, or IDE.
If you want to ignore a file that is already checked in, you must untrack the file before you add a rule to ignore it. From your terminal, untrack the file.
$ git rm --cached FILENAMEGitHub Docs: Configuring ignored files for all repositories on your computer
You can also create a global .gitignore file to define a list of rules for ignoring files in every Git repository on your computer. For example, you might create the file at ~/.gitignore_global and add some rules to it.
Configure Git to use the exclude file ~/.gitignore_global for all Git repositories.
$ git config --global core.excludesfile ~/.gitignore_globalGitHub Docs: Excluding local files without creating a .gitignore file]
If you don't want to create a .gitignore file to share with others, you can create rules that are not committed with the repository. You can use this technique for locally-generated files that you don't expect other users to generate, such as files created by your editor.
Use your favorite text editor to open the file called .git/info/exclude within the root of your Git repository. Any rule you add here will not be checked in, and will only ignore files for your local repository.
- Open Terminal.
- Navigate to the location of your Git repository.
- Using your favorite text editor, open the file
.git/info/exclude.
GitHub Pages will use Jekyll to build your site by default. If you want to use a static site generator other than Jekyll, disable the Jekyll build process by creating an empty file called .nojekyll in the root of your publishing source, then follow your static site generator's instructions to build your site locally.
Prevents GitHub Pages from ignoring files that begin with an underscore.
ACKNOWLEDGMENTS.md lists of all contributors to your project.
Similar to the CONTRIBUTORS.md file.
CHANGELOG.md lists of all the changes to your project.
This file might also be named CHANGES, HISTORY, NEWS, RELEASES, VERSIONS, etc.
Examples
- https://keepachangelog.com/en/1.0.0/
- https://github.com/conventional-changelog/conventional-changelog
- https://github.com/github-changelog-generator/github-changelog-generator
You can add a CITATION.cff file to the root of a repository to let others know how you would like them to cite your work. The citation file format is plain text with human- and machine-readable citation information.
Repository administrators can define exactly which people and teams need to review projects using the CODEOWNERS file. This feature automatically assigns reviewers based on Code Owners when a pull request changes any owned files, using the same syntax as the .gitignore file.
Use the CODEOWNERS file to ensure that changes to specific areas of the codebase are always reviewed by those with the most expertise.
A code of conduct defines standards for how to engage in a community. It signals an inclusive environment that respects all contributions. It also outlines procedures for addressing problems between members of your project's community. For more information on why a code of conduct defines standards and expectations for how to engage in a community, see the Open Source Guide.
To help your project contributors do good work, you can add a file with contribution guidelines to your project repository's root, docs, or .github folder. When someone opens a pull request or creates an issue, they will see a link to that file. The link to the contributing guidelines also appears on your repository's contribute page.
For the repository owner, contribution guidelines are a way to communicate how people should contribute.
For contributors, the guidelines help them verify that they're submitting well-formed pull requests and opening useful issues.
For both owners and contributors, contribution guidelines save time and hassle caused by improperly created pull requests or issues that have to be rejected and re-submitted.
- GitHub Docs: Setting guidelines for repository contributors
- GitHub Docs: Encouraging helpful contributions to your project with labels
- GitHub Docs: About community management and moderation
- GitHub Docs: Setting up your project for healthy contributions
- GitHub Docs: Encouraging helpful contributions to your project with labels
- GitHub Docs: Moderating comments and conversations
- Open Source Guides: Building Welcoming Communities
CONTRIBUTORS.md is a file that lists all the contributors to a project. It is a great way to show your community that you care about your project and its members.
Licenses are vital in open source repositories, because they set the rules for how others are allowed to use, change, and contribute to your project. In fact, if you don't add an open source license to a project, it is not technically open source -- in that case, it could be considered copyrighted work.
You can include an open source license in your repository to make it easier for other people to contribute.
When you include a detectable license in your repository, people who visit your repository will see it in the top right of the repository page.
If you go to "Add file" dropdown in your repo to create a new file and start naming with "License", a button will appear to the right for you to select a license template.
- GitHub Docs: Adding a license to a repository
- GitHub Docs: Licensing a repository
- https://choosealicense.com/
The README.md is the landing page for your project. It's the first thing people see when they visit your project's GitHub page and helps them understand, at a glance, whether your project is something that will be useful to them.
A README.md typically includes information on:
- What the project does
- The features and benefits of the project
- How users can get started with the project
- Where users can get help with your project
- Who maintains and contributes to the project
Including some short documentation is a good way to help visitors get started. Some repo owners prefer to keep more extensive documentation on an externally facing website while others will use a docs folder in their project or the repository wiki.
At a minimum you should include:
- Installation instructions
- Completing essential tasks
- Customizing and configuring
You can give instructions for how to report a security vulnerability in your project by adding a security policy to your repository.
When someone creates an issue in your repository, they will see a link to your project's security policy.
- GitHub Docs: Adding a security policy to your repository
- GitHub Docs: Creating a default community health file
You can create a SUPPORT file to let people know about ways to get help with your project.
When someone creates an issue in your repository, they will see a link to your project's SUPPORT file.
- GitHub Docs: Adding support resources to your project
- GitHub Docs: Creating a default community health file
In this file you can provide instructions for users on how to upgrade to the latest version of your project.
FUNDING file displays a sponsor button in your repository to increase the visibility of funding options for your open source project.
When you create an issue template for your repository using the issue template builder or with issue forms, contributors can select the appropriate template when they open new issues in the repository.
Issue templates are helpful when you want to provide guidance for opening issues while allowing contributors to specify the content of their issues. If you want contributors to provide specific, structured information when they open issues, issue forms help ensure that you receive your desired information.
- GitHub Docs: About issue and pull request templates
- GitHub Docs: Configuring issue templates for your repository
See .github/ISSUE_TEMPLATE/bug_report.md
When you add a pull request template to your repository, project contributors will automatically see the template's contents in the pull request body.
In the body of the file you could include:
- A tasklist of steps to follow before submitting the pull request.
- A reference to a related issue in your repository.
- Request a description of the changes proposed in the pull request.
- @mentions of the person or team responsible for reviewing proposed changes.
- GitHub Docs: About issue and pull request templates
- GitHub Docs: Creating a pull request template for your repository
- GitHub Docs: Linking a pull request to an issue
- Using keywords in issues and pull requests
You can customize the issue template chooser that people see when creating a new issue in your repository by adding a config.yml file to the .github/ISSUE_TEMPLATE folder.
By setting blank_issues_enabled to false people will be require to usea template when creating new issues. If you set blank_issues_enabled to true, people will have the option to open a blank issue.