A reliable Git and GitHub workflow gives a small project a clear history, safer collaboration, and a practical recovery path when a change goes wrong. This beginner-friendly checklist walks through repository setup, feature branches, commits, pull requests, merge conflicts, releases, and safe rollbacks so you can repeat the process on your next task without guessing which command comes next.
Overview
Git is the version-control system that records changes in a project, while GitHub is a hosted platform commonly used to store Git repositories, review changes, and coordinate work. You can use Git locally without GitHub, but combining them creates a useful workflow: work in a branch, save focused commits, open a pull request, review the difference, and merge only after the change is understood.
For a small project, the best workflow is usually simple rather than heavily automated. Keep the default branch in a usable state, create a short-lived branch for each feature or fix, and make commits that describe one logical step. Before opening a pull request, run the project’s tests, formatter, linter, or build command as appropriate. A clear history is not just documentation; it makes debugging and recovery easier.
If you are learning web development, use this workflow alongside a project tutorial such as the full-stack React and Node.js task manager guide. Git becomes easier to understand when each branch contains a visible, meaningful change.
A minimal mental model
- Working tree: the files currently in your project folder.
- Staging area: the changes selected for the next commit.
- Commit: a saved snapshot with a message.
- Branch: a movable line of development with its own commit history.
- Remote: a repository location such as a GitHub repository.
- Pull request: a proposal to merge one branch into another, usually with discussion and review.
Checklist by scenario
Starting a new local project
- Create or enter the project directory:
mkdir my-projectfollowed bycd my-project. - Initialize Git:
git init. - Add a suitable
.gitignorefile before staging files. Exclude generated output, dependency directories, local environment files, and secrets where relevant. - Inspect the folder with
git status. - Stage the intended files with
git add ., or stage specific paths when you want tighter control. - Create the first snapshot:
git commit -m 'Initial project setup'. - Create an empty repository on GitHub, then connect it as a remote. For example:
git remote add origin URL. - Push the branch and set its upstream:
git push -u origin main. Use the branch name configured for your project if it differs.
Before the first push, check for passwords, API keys, private certificates, and local configuration files. A .gitignore prevents many accidental additions, but it does not remove a secret that has already been committed.
Starting a feature or fix
- Update your local default branch:
git switch main, thengit pull --ff-only origin main. - Create and switch to a focused branch:
git switch -c feature/add-search. Use a name that describes the work. - Make a small change, then inspect it with
git diff. - Run relevant checks. These might include unit tests, a linter, a formatter, or a local build.
- Stage only the files that belong to the change:
git add path/to/file. - Review staged content with
git diff --staged. - Commit a complete logical step:
git commit -m 'Add task search'. - Push the branch:
git push -u origin feature/add-search.
Several small, understandable commits can be more useful than one large commit, especially while a change is being reviewed. Avoid committing temporary debugging output, editor files, or unrelated formatting changes.
Opening and completing a pull request
On GitHub, select the pushed branch and open a pull request against the project’s default branch. The description should explain what changed, why it changed, how it was tested, and anything a reviewer should pay attention to. Link an issue or task when one exists.
Use this pull request checklist:
- The title describes the user-visible or technical outcome.
- The branch contains only related work.
- The proposed base branch is correct.
- Tests, formatting, linting, or build checks have been run.
- Documentation, configuration, and migration changes are included when needed.
- No secrets or unnecessary generated files appear in the diff.
- Review comments have been answered or resolved intentionally.
After approval, merge using the repository’s agreed option. Squashing can keep a small project’s default branch concise, while preserving individual commits can show the sequence of development. The important point is consistency and a record of the decision. Delete the remote feature branch after merging if it is no longer needed, then update locally with git switch main and git pull --ff-only origin main.
Resolving a merge conflict
- Update the target branch and return to your feature branch:
git switch feature/add-search. - Bring the latest target branch into it, for example with
git merge main. - Run
git statusto see conflicted files. - Open each file and find the conflict markers:
<<<<<<<<,=======, and>>>>>>>. - Edit the file so it contains the intended final result, then remove every conflict marker.
- Stage each resolved file with
git add path/to/file. - Complete the merge with
git commit, or follow the command Git prints for the current operation. - Run the full relevant checks before pushing:
git push.
Do not choose one side automatically just because it is yours. Read the surrounding code and confirm that imports, tests, configuration, and behavior still fit together.
Releasing and rolling back
When a known commit is ready for a release or milestone, create an annotated tag such as git tag -a v1.0.0 -m 'First stable release', then share it with git push origin v1.0.0. Use the project’s own versioning convention and confirm the commit before tagging with git log --oneline.
For an unsafe change that has already been shared, prefer a new corrective commit. On a shared branch, git revert COMMIT_ID creates a commit that reverses the selected change without rewriting the existing history. Push and review that revert like any other change. Reserve git reset for local work or situations where the team explicitly agrees to rewrite history; a force push can remove commits other people rely on.
What to double-check
- Before committing: Run
git status, inspectgit diff, and verify that staged files are intentional. - Before pushing: Check the branch name, run the project checks, and confirm that no credentials or personal files are included.
- Before opening a pull request: Compare the branch with the target branch, read the complete diff, and describe testing honestly.
- Before merging: Confirm that required reviews and checks are complete, conflicts are resolved, and the target branch is still current.
- Before reverting: Identify the exact commit with
git log --onelineand consider whether a targeted fix is safer than reversing a larger change. - Before deleting a branch: Confirm that its work is merged or intentionally abandoned and that any useful commit or tag remains reachable.
For projects involving API keys or environment configuration, treat Git review as part of your debugging routine. A useful companion is the API debugging toolkit, especially when a failing request may be caused by malformed data rather than application logic.
Common mistakes
Working directly on the default branch
Direct commits make review and rollback less predictable. Even for a solo project, a short-lived branch creates a deliberate checkpoint and makes the change easier to inspect.
Using git add . without checking the result
The command is convenient, but it can stage files you did not intend to share. Follow it with git status and git diff --staged.
Writing vague commit messages
Messages such as changes or fixes do not help later. Prefer an outcome, such as Handle empty search results.
Resolving conflicts by accepting all incoming changes
Conflict resolution is a code decision, not a button-clicking exercise. Check behavior, tests, and adjacent edits after combining the versions.
Rewriting shared history to hide a mistake
For published commits, a revert is usually easier for collaborators to understand than a reset followed by a force push. If history must be rewritten, communicate the exact branch, reason, and recovery steps first.
Committing secrets
If a secret enters Git history, deleting the current line is not necessarily enough because earlier commits may retain it. Stop using the exposed credential, follow the relevant rotation process, and consult your platform or team guidance for history cleanup.
When to revisit
Keep this checklist nearby whenever you begin a feature branch, prepare a pull request, resolve a conflict, publish a release, or recover from an unsafe change. Revisit the project’s written workflow before a new contributor joins, before a major planning cycle, or when the repository adds automated checks, protected branches, release automation, or a different merge policy.
Git commands are stable concepts, but repository settings and GitHub interface details can change. If a command behaves differently, read its local help with git help COMMAND and check the repository’s contribution guidance rather than copying an old workaround. For continued learning, connect this workflow to a practical JavaScript project, then use the resulting history to explain your decisions in a portfolio or interview. A consistent cycle—update, branch, inspect, test, commit, review, merge, and tag—turns Git from a source of anxiety into one of the most useful developer tools in a small project.
