Files and folders in a project
Beginner Core Git Git CLI VS Code UI IntelliJ UI
Why this matters
You will spend your Git life inside project folders that someone else organized. Knowing the conventions tells you where to put a new document, which file to change to fix a typo, and, above all, which files to leave alone. Half of the "how did that get into my commit?" problems come from not knowing that a folder was generated.
The anatomy of a project
Most projects, in any language, look roughly like this. The playground follows the pattern:
trailguide/
├── README.md what this is, how to run it — the front door
├── CONTRIBUTING.md the team's rules for contributing
├── .gitignore files Git must never track
├── .gitlab-ci.yml automated checks on GitLab
├── .github/workflows/ci.yml the same for GitHub
├── docs/ documentation (Markdown), images
├── data/ data files the program reads
├── src/ source code
├── tests/ automated tests
└── .git/ Git's history — never edit by hand| Item | What it is for | Typical names |
|---|---|---|
| README | The first thing anyone reads: what the project is, how to run it, where the docs are | README.md |
| Documentation | Guides, references, decisions, in Markdown | docs/, documentation/, wiki/ |
| Source code | The program itself | src/, app/, lib/, or folders named after the language's habits |
| Tests | Programs that check the program | tests/, test/, spec/, __tests__/ |
| Data | Files the program reads, samples, fixtures | data/, fixtures/, assets/ |
| Configuration | Settings for tools and the program: which Python version, how to lint, where to deploy | pyproject.toml, package.json, .editorconfig, Dockerfile, *.yml |
| Dependency manifests and lock files | The list of libraries the project needs, and the exact versions that were installed | package.json + package-lock.json, requirements.txt, poetry.lock, Cargo.lock |
| Pipeline definitions | What runs automatically after a push | .gitlab-ci.yml, .github/workflows/ |
| Generated output | Files produced by a build or a tool; can always be regenerated | build/, dist/, target/, out/, __pycache__/, node_modules/ |
| Hidden folders | Tool state, starting with a dot | .git/, .venv/, .idea/, .vscode/ |
| Licence and changelog | Legal terms; a human-readable history of releases | LICENSE, CHANGELOG.md |
What you may touch
Think in three colours:
| Colour | Files | Rule |
|---|---|---|
| Green: edit freely | docs/, README.md, CHANGELOG.md, data files you own, your own scripts |
Edit, commit, open a merge request. |
| Amber: edit with care | Source code, tests, configuration | Small, understood changes only; run the tests; ask a developer to review. |
| Red: never by hand | .git/, lock files, generated output, node_modules/, .venv/, anything listed in .gitignore |
Leave alone. If they appear in git status, something is wrong with .gitignore, not with you. |
Hidden files
Files and folders whose names start with a dot are hidden by default on macOS and Linux. Several of the most important ones are hidden: .git (the whole history), .gitignore, .gitlab-ci.yml. Each tool has a way to show them.
ls hides dotfiles; ls -a shows all of them:
$ ls -a.
..
.git
.github
.gitignore
.gitlab-ci.yml
.markdownlint.json
CONTRIBUTING.md
README.md
data
docs
src
tests. is the current folder and .. its parent; ignore them. On Windows, Git Bash behaves the same; PowerShell uses Get-ChildItem -Force.
The Explorer (the top icon in the Activity Bar, or Ctrl+Shift+E / ⇧⌘E) shows dotfiles such as .gitignore but hides the .git folder on purpose. To confirm a folder is a repository, look at the status bar: a branch name at the bottom left means Git is active. To show .git anyway: File → Preferences → Settings, search files.exclude, and remove the **/.git pattern (rarely a good idea).
The Project tool window (Alt+1 / ⌘1) shows dotfiles and hides .git. Confirm Git is active from the branch name at the bottom right of the status bar, or Git → Show Git Log. Generated folders such as __pycache__ may appear greyed out or excluded; that is IntelliJ marking them as not worth indexing.
Open the project, then Code → Repository. The file list shows every tracked file, dotfiles included (.gitignore, .gitlab-ci.yml). .git is never shown, because on the server the history is stored differently; the web UI shows it as Commits and Branches instead. Files that are ignored never appear, because they were never pushed.
Open the repository's Code tab. Dotfiles such as .gitignore and the .github folder are listed; .git is not. Ignored files never appear. Click a file to read it, or the pencil icon to edit it in the browser (Section 7 covers that).
Common mistakes
- Committing generated output.
build/or__pycache__/shows up ingit status; yougit add .and commit a thousand files. Prevention: check that.gitignorelists them (lesson 4.3). - Editing a lock file to "fix" a version conflict. It breaks installs for everyone. Ask the developer who owns the dependency.
- Putting documentation next to the source. Most teams keep docs in
docs/; anotes.mdat the root ofsrc/will be moved or deleted. Look at where existing documentation lives and follow it. - Saving files in the wrong folder. Your editor's "Save as" may default to your home folder. Check that the file appears in the project tree before you look for it in
git status.
Try it yourself
Goal: find every hidden item in the playground and classify each top-level item by colour.
- In a terminal inside
trailguide, runls -a. - For each item, say green, amber or red before opening the solution.
- Open
.gitignorein your editor and read the four groups of lines.
Expected result: you found .git, .github, .gitignore, .gitlab-ci.yml and .markdownlint.json, and .gitignore lists __pycache__/, .venv/, .env and editor folders.
Show solution
Green: README.md, CONTRIBUTING.md, docs/, data/. Amber: src/, tests/, .gitlab-ci.yml, .github/, .gitignore, .markdownlint.json (configuration: edit only when you know why). Red: .git/ and anything .gitignore names (__pycache__/, .venv/, .env, .idea/, .vscode/, .DS_Store).