Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/joelparkerhenderson/github-special-files-and-paths
GitHub special files and paths, such as README, LICENSE, .github, docs, dependabot, workflows.
https://github.com/joelparkerhenderson/github-special-files-and-paths
Last synced: 15 days ago
JSON representation
GitHub special files and paths, such as README, LICENSE, .github, docs, dependabot, workflows.
- Host: GitHub
- URL: https://github.com/joelparkerhenderson/github-special-files-and-paths
- Owner: joelparkerhenderson
- Created: 2018-03-26T21:24:42.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2023-09-24T19:50:19.000Z (about 1 year ago)
- Last Synced: 2024-05-20T04:11:39.702Z (6 months ago)
- Homepage:
- Size: 94.7 KB
- Stars: 271
- Watchers: 12
- Forks: 27
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-developing - GitHub special files and paths
- jimsghstars - joelparkerhenderson/github-special-files-and-paths - GitHub special files and paths, such as README, LICENSE, .github, docs, dependabot, workflows. (Others)
README
# GitHub special files and paths
GitHub uses special files such as `README` and `LICENSE`, special paths such as `/.github` and `/docs`, and special repositories like `/.github` or `/`, to improve repository management and developer interactions. This page is a summary. We welcome pull requests.
- Introduction
- README
- <username>/<username>/README
- <org>/<.github[-private]/README
- CHANGELOG
- LICENSE
- SUPPORT
- SECURITY
- CODE_OF_CONDUCT
- CONTRIBUTING
- CONTRIBUTORS
- AUTHORS
- ACKNOWLEDGMENTS
- CODEOWNERS
- ISSUE_TEMPLATE
- PULL_REQUEST_TEMPLATE
- CITATION.cff
- FUNDING.yml
- dependabot.yml
- Workflows
- Jekyll
- Tracking
Introduction
GitHub special files can typically be written with a variety of formats and file name extensions:
* Freeform text, such as `README` or `README.txt`.
* Markup formats, such as `README.markdown` or `README.asciidoc` - see [markups](https://github.com/github/markup/blob/master/README.md#markups)
* Custom syntaxes, such as the file `CODEOWNERS`.
GitHub special files are typically located at the repository top level or in special paths:
* `./` is the top level
* `./.github` is a hidden dot file directory specifically for GitHub files
* `./docs` is a typical documentation directory.
* Custom paths, such as the directory `ISSUE_TEMPLATE`.
The special files and paths are sometimes also known as community health files, recommended repository files, well-known configurations, etc.
For a general overview see [building a strong community](https://help.github.com/categories/building-a-strong-community/) and [GitHub's Open Source Guides](https://opensource.guide/).
README
* File: `README` or `README.txt` or `README.md` etc.
* Help:
* Directories: `./` `./.github/` `./docs/`
* Awesome: list:
A README file describes your project, what it does, why it is useful, etc.
This file is often the first item a visitor will see when visiting your repository, because GitHub automatically shows this file to repository visitors. README files in subdirectories will display when visitors view that subdirectory in the GitHub website.
Profile README
* Repository: `/`
* Help:
A README file in the root of a repository that has the same name as your username, e.g. [mojombo/mojombo](https://github.com/mojombo/mojombo), will be shown at the top of your profile page.
Organization README
* Repository: `/.github` or `/.github-private`
* Help:
A README file in the root of an organization repository called `.github`, .e.g. [github/.github](https://github.com/github/.github), will be shown to visitors at the top of the organization profile page. An equivalent file in the root of an organization repository called `.github-private` will be shown to logged in organization members.
CHANGELOG
* File: `CHANGELOG` or `CHANGELOG.txt` or `CHANGELOG.md` etc.
* Directories: `./` `./.github/` `./docs/`
A CHANGELOG file describes the changes in the project, such as version changes, feature additions, and bug fixes.
LICENSE
* File: `LICENSE` or `LICENSE.txt` or `LICENSE.md` etc.
* Help:
* Directories: `./` `./.github/` `./docs/`
This file explains the repository's legal license, such as any legal rights, any copyright restrictions, etc. If you include a detectable license in your repository, people who visit your repository will see it at the top of the repository page.
If you want help to choose a license, then try https://choosealicense.com
If your project is significant, or contains other peoples' work or intellectual property, then you may want to consult with a lawyer who can help you with your specific goals and needs. If you don't provide a license, then in some locations a default copyright law will apply.
SUPPORT
* File: `SUPPORT` or `SUPPORT.txt` or `SUPPORT.md` etc.
* Directories: `./` `./.github/` `./docs/`
This file explains how a reader can get help with the repository and project. GitHub links this file on the page "New Issue". Unlike the "CONTRIBUTING" file, GitHub does not link this file on the page "New Pull Request".
Default `SUPPORT` files that apply across all repositories can be placed in an organization's `.github` repository, see .
SECURITY
* File: `SECURITY` or `SECURITY.txt` or `SECURITY.md` etc.
* Help:
* Directories: `./` `./.github/` `./docs/`
This file explains the project's security policies, such as a list of versions that are currently being maintained with security updates. This file also provides instructions on how users can submit a report of a vulnerability.
GitHub links to this file, under the "Policy" link on the "Security" tab of your repository.
Default `SECURITY` files that apply across all repositories can be placed in an organization's `.github` repository, see .
CODE_OF_CONDUCT
* File: `CODE_OF_CONDUCT` or `CODE_OF_CONDUCT.txt` or `CODE_OF_CONDUCT.md` etc.
* Help:
* Directories: `./` `./.github/` `./docs/`
* Awesome: list:
This file explains how to engage in a community, and how to foster an inclusive environment that respects all people, and how to address any problems among members of your project's community.
Default `CODE_OF_CONDUCT` files that apply across all repositories can be placed in an organization's `.github` repository, see .
CONTRIBUTING
* File: `CONTRIBUTING` or `CONTRIBUTING.txt` or `CONTRIBUTING.md` etc.
* Help:
* Directories: `./` `./.github/` `./docs/`
* Awesome: list:
This file explains how people can contribute to the project. This file can help verify people are submitting well-formed pull requests and opening useful issues.
GitHub links to this file, on the page "New Issue" and the page "New Pull Request".
Default `CONTRIBUTING` files that apply across all repositories can be placed in an organization's `.github` repository, see .
CONTRIBUTORS
* File: `CONTRIBUTORS` or `CONTRIBUTORS.txt` or `CONTRIBUTORS.md` etc.
* Directories: `./` `./.github/` `./docs/`
This file explains who has contributed to the project. When we use a `CONTRIBUTORS` file in our projects, we ask people how they want to be listed, such as by their name, handle, email address, website link, etc.
Compare this file to the file `AUTHORS`.
AUTHORS
* File: `AUTHORS` or `AUTHORS.txt` or `AUTHORS.md` etc.
* Directories: `./` `./.github/` `./docs/`
This file lists people who are significant authors of the project, such as the people who are legally related to the work. The GNU project states "Only the contributions that are legally significant for copyright purposes (see Legally Significant) need to be listed. Small contributions, bug reports, ideas, etc., can be omitted."
Compare this file to the file `CONTRIBUTORS`.
ACKNOWLEDGMENTS
* File: `ACKNOWLEDGMENTS` or `ACKNOWLEDGMENTS.txt` or `ACKNOWLEDGMENTS.md` etc.
* Directories: `./` `./.github/` `./docs/`
This file explains relevant related work, such as other projects that are dependencies, or libraries, or modules, or have their own copyrights or licenses that you want to include in your project.
CODEOWNERS
* File: `CODEOWNERS`
* Help:
* Directories: `./` `./.github/` `./docs/`
This file defines individuals or teams that are responsible for code in a repository.
Code owners are automatically requested for review when someone opens a pull request that modifies code that they own. When someone with admin or owner permissions has enabled required reviews, they also can optionally require approval from a code owner before the author can merge a pull request in the repository.
ISSUE_TEMPLATE
* File: `ISSUE_TEMPLATE`
* Help:
* Directories: `./` `./.github/` `./docs/` or `./ISSUE_TEMPLATE/`
* Awesome: list:
When you add an issue template to your repository, project contributors will automatically see the template's contents in the issue body. Templates customize and standardize the information you'd like included when contributors open issues.
See
To add multiple issue templates to a repository create an `ISSUE_TEMPLATE/` directory in your project root. Within that `ISSUE_TEMPLATE/` directory you can create as many issue templates as you need, for example `ISSUE_TEMPLATE/bugs.md`.
Default `ISSUE_TEMPLATE` files that apply across all repositories can be placed in an organization's `.github` repository, see .
PULL_REQUEST_TEMPLATE
* File: `PULL_REQUEST_TEMPLATE` or can be a subdirectory
* Help:
* Directories: `./` `./.github/` `./docs/`
* Awesome: list:
This file triggers project contributors to automatically see the template's contents in a new pull request body. The template can customize and standardize the information you'd like included when contributors create pull requests.
See
You can create a `PULL_REQUEST_TEMPLATE/` subdirectory in any of the supported folders to contain multiple pull request templates. Use the template query parameter to specify the template that will automatically fill the pull request body. For more information, see "[About automation for issues and pull requests with query parameters.](https://help.github.com/articles/about-automation-for-issues-and-pull-requests-with-query-parameters/)"
CITATION.cff
* File: `CITATION.cff` or `CITATION` or `CITATIONS` or `CITATION.bib` Or `CITATIONS.bib` or `CITATION.md` or `CITATIONS.md`
* Help:
* Directories: `./` or special case `inst/CITATION` for R packages.
This file explains how you would like people to cite your work. The citation file format is plain text with human-readable and machine-readable citation information.
When you add this file to the default branch root directory of your repository, then GitHub automatically links to it from the repository landing page.
FUNDING.yml
* File: `.github/FUNDING.yml`
* Help:
You can configure your sponsor button by adding a file in your repository on the default branch. You can configure the button to include sponsored developers in GitHub Sponsors, external funding platforms, or a custom funding URL.
Default `FUNDING.yml` files that apply across all repositories can be placed in an organization's `.github` repository, see .
dependabot.yml
* File: `.github/dependabot.yml`
* Help:
Dependabot is a GitHub tool that provides automated dependency updates. To enable updates, create a Dependabot configuration file and add it to a repository. The file describes the dependencies to update, where dependency manifests are located, etc. If Dependabot discovers that an update is available, then Dependabot sends you a pull request to update your dependency.
Workflows
* Directory: `.github/workflows`
* Help:
A workflow is a configurable automated process made up of one or more jobs. You must create a YAML file to define your workflow configuration. Workflow files use YAML syntax, and must have file extension `.yml` or `.yaml`.
## CNAME
* File: `CNAME`
* Help:
When using GitHub Pages with a custom domain ( rather than ), the `CNAME` file specifies the domains that should be directed to the generated site.
Jekyll
Files and directories: see below
* Help:
GitHub uses Jekyll to compile static sites for hosting through its GitHub Pages service. Jekyll configuration is read directly from the repository.
The following files and directories are used by Jekyll:
* `_config.yml`
* `_drafts/`
* `_includes/`
* `_layouts/`
* `_posts/`
* `_data/`
* `_sass/`
* `_site/`
* `.jekyll-metadata`
* `index`
All other files in the repository are included in the generated site without additional processing.
Tracking
* Package: github-special-files-and-paths
* Version: 5.1.0
* Created: 2017-08-22T00:00:00Z
* Updated: 2023-08-02T13:01:05Z
* License: GPL-2.0-or-later or contact us for custom license
* Contact: Joel Parker Henderson ([email protected])