Skip to content

An educational repo created to provide example configuration files for some typical GitHub use cases.

License

Notifications You must be signed in to change notification settings

danpoynor/special-github-files

✨ Special GitHub Files ✨

Contributors Forks Stargazers Issues Unlicense License LinkedIn

Description

A collection of GitHub repo files with brief explinations and links to deeper learnings.

Usage

  • 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.

FAQ

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.


Folder Structure

β”œβ”€β”€ .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

Special Files


πŸ“„ .gitignore

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/ and node_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 .gitignore file in to your repository.

    GitHub maintains an official list of recommended .gitignore files 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 FILENAME

GitHub 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_global

GitHub 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.

  1. Open Terminal.
  2. Navigate to the location of your Git repository.
  3. Using your favorite text editor, open the file .git/info/exclude.

Resources


πŸ“„ .nojekyll

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.

Resources


πŸ“„ ACKNOWLEDGMENTS.md

ACKNOWLEDGMENTS.md lists of all contributors to your project.

Similar to the CONTRIBUTORS.md file.


πŸ“„ CHANGELOG.md

CHANGELOG.md lists of all the changes to your project.

This file might also be named CHANGES, HISTORY, NEWS, RELEASES, VERSIONS, etc.

Examples

Resources


πŸ“„ CITATION.cff

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.

Resources


πŸ“„ CODEOWNERS

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.

Resources


πŸ“„ CODE_OF_CONDUCT.md

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.

Resources


πŸ“„ CONTRIBUTING.md

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.

Examples

Resources


πŸ“„ CONTRIBUTORS.md

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.

Resources


πŸ“„ LICENSE

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.

Resources


πŸ“„ README.md

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

Resources


πŸ“„ SECURITY.md

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.

Resources


πŸ“„ SUPPORT.md

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.

Resources


πŸ“„ UPGRADING.md

In this file you can provide instructions for users on how to upgrade to the latest version of your project.


πŸ“„ .github/FUNDING.yml

FUNDING file displays a sponsor button in your repository to increase the visibility of funding options for your open source project.

Resources


πŸ“„ .github/ISSUE_TEMPLATE/bug_report.md

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.

Resources


πŸ“„ .github/ISSUE_TEMPLATE/feature_request.md

See .github/ISSUE_TEMPLATE/bug_report.md


πŸ“„ .github/PULL_REQUEST_TEMPLATE.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.

Resources


πŸ“„ .github/ISSUE_TEMPLATE/config.yml

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.

Resources


About

An educational repo created to provide example configuration files for some typical GitHub use cases.

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

No releases published

Sponsor this project

Packages

No packages published