Recording in the Mission Log

Creating a Permanent Record

A commit is a snapshot of your project at a specific moment—like a photograph of all your spacecraft systems. Once created, commits are permanent records in your mission history.

Making Your First Commit

After staging files with git add, commit them:

git commit -m "Initial commit: Add README"

The -m flag lets you include a message inline. Without it, Git opens your default editor.

Commit Messages: Why They Matter

Your commit message explains why you made changes. Future you (and teammates) will read these messages to understand project history.

Good Commit Messages

Add user authentication system
Fix navigation bug in mobile view
Update dependencies to patch security vulnerability
Refactor database connection logic for clarity

Bad Commit Messages

fixed stuff
asdf
updates
changes
WIP

Be descriptive! Your future self will thank you.

Commit Message Best Practices

• Use present tense: "Add feature" not "Added feature"
• Be specific: "Fix login timeout error" not "Fix bug"
• Keep first line under 50 characters: It's the commit title
• Add details if needed: After first line, add empty line then explanation
• Explain why, not just what: The diff shows what changed; explain why

Multi-line Commit Messages

For complex changes, use detailed messages:

git commit

This opens your editor. Write:

Add real-time telemetry monitoring

Implements WebSocket connection to mission control for live data.
Includes automatic reconnection on disconnect and buffering
during connection loss. Resolves issue #47.

First line is the summary. After blank line, add details.

Commit Frequently

Small, frequent commits are better than large, infrequent ones:

• Easier to understand changes
• Easier to find when bugs were introduced
• Easier to revert specific changes
• Better collaboration with teammates

Commit whenever you complete a logical unit of work.

The Commit Workflow

1. Make changes to files
2. Review changes: git status and git diff
3. Stage changes: git add
4. Review staged changes: git diff --staged
5. Commit: git commit -m "message"
6. Verify: git log

Shortcut: Stage and Commit

To stage all modified (but not new) files and commit:

git commit -am "Update navigation algorithms"

The -a flag auto-stages modified files. Careful: won't add new files!

Amending the Last Commit

Forgot something? Fix the most recent commit:

git add forgotten-file.txt
git commit --amend

This adds the file to the previous commit. You can also change the commit message.

Warning: Only amend commits that haven't been pushed!

What's in a Commit?

Each commit contains:

• Snapshot: Complete state of all tracked files
• Author info: Name and email from your config
• Timestamp: When the commit was created
• Commit message: Your description
• Parent commit(s): Link to previous commit(s)
• SHA-1 hash: Unique identifier for this commit

Commit Hash

Every commit gets a unique hash like:

a3f5e2b8c1d9f7e6a4b2c8d3e5f7a9b1c3d5e7f9

This identifies the commit forever. You can reference commits by their hash (or the first 7 characters).

Atomic Commits

Make commits "atomic"—each commit should represent one logical change:

• Good: One commit fixes navigation bug, another updates documentation
• Bad: One commit with bug fix, documentation, refactoring, and new feature

When to Commit

Commit when you:

• Complete a feature (even if small)
• Fix a bug
• Refactor code
• Update documentation
• Reach a stable state

Some developers commit hourly. Others commit after each small task. Find your rhythm.

Commits are Permanent

Commits are (nearly) permanent. Even if you "delete" them, they often remain in Git's database. This is good—it means you can't accidentally lose work.

Next: Examining Changes

You can now create snapshots of your work. Next, we'll learn to examine differences between commits, helping you understand exactly what changed and when.