Distinguish your files, the staged snapshot and history

Three places can contain three versions

The working tree is what your editor sees. The index, often called the staging area, holds the snapshot proposed for the next commit. A commit records that snapshot with metadata and parent history. Editing a file after staging it does not silently update the staged version. This distinction lets you organize a reviewable change, but it also lets you accidentally commit an older edit than the one you just tested.

git diff compares unstaged working-tree changes with the index. git diff --cached compares staged changes with the current commit. git status --short summarizes both. In a two-character status such as MM capacity.py, the first column describes an index change and the second a working-tree change. Do not read that as one generic “modified” flag; there are two snapshots to inspect.

Git tracks file contents and paths; it is not a live record of every keystroke, every environmental dependency or every untracked file. A commit of a script does not include your interpreter installation, cloud permissions, private data or unsaved editor buffer. A useful project also records its runtime requirements, fixture, tests and execution limits.

Initialize only the new exercise directory

Copy the downloaded fixture into a new directory named script-project. Open a terminal in that directory and verify its path before initializing. These commands affect this repository only:

git init -b main
git config user.name 'Course Learner'
git config user.email 'learner@example.invalid'
git status --short

The local identity is fictional and is set without --global. It labels the practice commits; it does not authenticate a remote service. If git init -b is unavailable on your older Git, initialize and rename the initial branch explicitly, or use a current supported Git version. The course expects the branch to be named main rather than depending on a machine's global default.

Create .gitignore with these four lines:

__pycache__/
*.pyc
reports/
.env

Ignored patterns guide handling of untracked files. They are not access controls, encryption or a promise that secrets never entered history. A file already tracked remains tracked even if a new pattern matches it. Verify what is staged before committing; do not assume an ignore file retroactively sanitized the repository.

A small program with one known defect

The requirement is exact: accept only integer percentages from 0 through 100, rejecting booleans and other types. Return REVIEW only when free percentage is below 10; exactly 10 returns OK. OK is a rule result, not proof that a device is healthy.

The starting fixture is intentionally wrong:

"""Deliberately flawed starting fixture: repair the exactly-10 boundary."""
def classify_free(percent):
    if type(percent) is not int or not 0 <= percent <= 100:
        raise ValueError('free percent must be an integer from 0 to 100')
    return 'REVIEW' if percent <= 10 else 'OK'

The <= in the return expression includes exactly 10. The validation line's <= 100 is correct and must not be changed. This distinction will matter when you repair the defect. A global search-and-replace for <= 10 can also match the beginning of <= 100 and accidentally reject the valid upper endpoint.

Run the tests below before modifying code. Five tests run; exactly the boundary test should fail. A different failure means your environment or fixture differs from the expected baseline. Investigate it before continuing. Do not change the expected value to make the known defect appear correct.

import unittest
from capacity import classify_free

class CapacityTests(unittest.TestCase):
    def test_below_boundary(self):
        self.assertEqual(classify_free(9),'REVIEW')
    def test_exact_boundary(self):
        self.assertEqual(classify_free(10),'OK')
    def test_above_boundary(self):
        self.assertEqual(classify_free(11),'OK')
    def test_endpoints(self):
        self.assertEqual(classify_free(0),'REVIEW')
        self.assertEqual(classify_free(100),'OK')
    def test_invalid_values(self):
        for value in [-1,101,True,'10',10.0,None]:
            with self.subTest(value=value), self.assertRaises(ValueError):
                classify_free(value)

if __name__ == '__main__':
    unittest.main()

Record a truthful baseline

python -m unittest -v
git add -- capacity.py test_capacity.py README.md .gitignore
git diff --cached
git diff --cached --check
git commit -m 'Add fixture with documented boundary defect'
git log --oneline -3

The test command fails intentionally at this stage; read its output rather than chaining commands under a rule that requires every line to succeed. The commit message discloses the defect. A known-failing exercise baseline is acceptable in this isolated teaching repository; it is not a recommendation to merge known defects into a protected production release.

git diff --cached --check checks certain whitespace problems; it does not run tests or certify functionality. A clean result is useful but narrower than the word “check” might suggest. Keep syntax, style, behavior, authorization and operational review as distinct evidence.

Exercise: inspect before broad staging

Create an untracked scratch-note.txt with a harmless local note and leave it out of the commit. Compare git status --short with the staged file list. Explain why git add . would have a wider scope than the explicit path list.

Worked reasoning

The note appears as untracked but is absent from the index. The next commit only includes the staged paths. Broad staging can include unrelated notes, test outputs or credentials, subject to ignore patterns. Explicit paths reduce accidental scope; they still require content review and do not make a secret-containing chosen file safe.

Reasoning model

A useful change set links a requirement, a failing test, a minimal code change and a passing verification. A green test suite only supports behavior covered by its tests. Review the diff for unrelated edits and secrets, not just the final output. Version control preserves history but does not make committed credentials safe; treat accidental credential exposure through the organization’s incident/rotation process.

Official reference for further study