Blog / Engineering · 8 min read ·
Git and GitHub for capstone teams: a practical workflow
Set up a shared repository, commit with clear messages, work on branches, review pull requests, and keep secrets out of your capstone code.
Sending code as zip files over Messenger works until two people edit the same file, or a laptop dies a week before the defense. Git keeps every version of your project, and GitHub gives your team one shared copy that everyone can work from safely.
This guide covers the commands you will use every day, a branch and pull request workflow for a team of three to five, and the habits that keep your repository clean and your passwords out of it.
One-time setup
Install Git from the official site, create a GitHub account for each member, and tell Git who you are. Use the same email address as your GitHub account so your commits are linked to your profile, which matters when the panel or your adviser checks who contributed.
git config --global user.name "Juan Dela Cruz"
git config --global user.email "juan.delacruz@example.com"
git config --global init.defaultBranch mainGitHub no longer accepts your account password for Git over HTTPS. Set up authentication using GitHub's current instructions, either a personal access token, an SSH key, or the GitHub CLI. Check GitHub's documentation for the steps, since they change from time to time.
Start or join a repository
One member, usually the team lead, creates the repository. Either start locally and push to a new empty GitHub repository, or create it on GitHub and clone it. The lead then adds the others as collaborators in the repository settings.
cd barangay-records
git init
git add .
git commit -m "chore: initial project setup"
git remote add origin https://github.com/your-team/barangay-records.git
git push -u origin maingit clone https://github.com/your-team/barangay-records.git
cd barangay-recordsWhat to put in .gitignore
The .gitignore file lists files Git should never track: secrets, dependencies that can be reinstalled, build output, and personal editor settings. GitHub offers templates per language when you create a repository. A typical file for a Laravel or Node.js capstone looks like this:
# Secrets and local configuration
.env
.env.*
!.env.example
# Dependencies (reinstall with composer install / npm install)
/vendor/
node_modules/
# Build output and caches
/public/build/
/public/hot
/storage/*.key
.next/
dist/
build/
# Logs and local databases
*.log
*.sqlite
# Editor and OS files
.vscode/
.idea/
.DS_Store
Thumbs.dbCommit a .env.example file with the same keys as .env but placeholder values, such as DB_PASSWORD=change-me. New members copy it to .env and fill in their own values. Never commit real database passwords, SMS gateway keys, or email credentials.
The commands you will use every day
Most of your work is a loop: get the latest changes, make a change, check it, stage it, commit it, and push it.
git status # what changed?
git pull # get teammates' latest work
git add app/Http/Controllers/ClearanceController.php
git diff --staged # review exactly what you are about to commit
git commit -m "feat(clearance): add request form for residents"
git pushStage specific files instead of using git add . every time. It stops you from committing debug files, screenshots, or a stray .env that slipped past your .gitignore.
Write commit messages your team can read
A clear commit history doubles as a record of who built what, which helps when writing your manuscript and when the panel asks about contributions. The Conventional Commits format is simple to follow: a type, an optional scope in parentheses, and a short description in the present tense.
| Type | Use it for | Example |
|---|---|---|
| feat | A new feature | feat(billing): compute water bill from meter readings |
| fix | A bug fix | fix(enrolment): prevent duplicate student numbers |
| docs | Documentation only | docs: add setup steps to README |
| style | Formatting, no logic change | style: format queue views |
| refactor | Restructuring without changing behaviour | refactor(reports): extract monthly totals query |
| test | Adding or fixing tests | test(billing): cover minimum charge rule |
| chore | Tooling, dependencies, setup | chore: update Laravel dependencies |
Avoid messages like update, fix, or final na talaga. If you cannot describe the commit in one line, it probably contains more than one change and should be split.
Branches and pull requests
Keep main working at all times, because it is what you will demo. Each feature or fix gets its own branch. When it is ready, open a pull request (PR) on GitHub so a teammate can review it before it is merged.
git switch main
git pull
git switch -c feature/queue-sms-alert
# ...work and commit as usual...
git add app/Services/SmsNotifier.php
git commit -m "feat(queue): send SMS when patient is three numbers away"
git push -u origin feature/queue-sms-alertAfter pushing, GitHub shows a prompt to open a pull request. In the description, say what changed, how to test it, and link the related task. The reviewer reads the diff, runs it locally if needed, and either approves or asks for changes. Once approved, merge it on GitHub and delete the branch.
git switch main
git pull
git switch feature/queue-sms-alert
git merge main
# only if Git reports conflicts: fix the files, then
git add path/to/resolved-file.php
git commit -m "chore: merge main into feature/queue-sms-alert"
git pushResolving merge conflicts
A conflict happens when two branches change the same lines. Git marks the conflicting section in the file with <<<<<<<, =======, and >>>>>>>. Open the file, keep the correct version (often a combination of both), delete the markers, test that the system still runs, then stage and commit. If you are unsure, ask the teammate who wrote the other change. Small, frequent pull requests cause far fewer conflicts than one large merge before the deadline.
A team workflow that works
| Practice | Who | How |
|---|---|---|
| Protect main | Team lead | Enable branch protection so changes to main require a pull request and one approval |
| Track tasks | Everyone | Use GitHub Issues or a Projects board; one issue per feature or bug |
| One branch per task | Each developer | Name branches feature/, fix/, or docs/ followed by a short description |
| Review every PR | A teammate other than the author | Check that it runs, matches the task, and contains no secrets |
| Pull daily | Everyone | Start each work session with git pull on main |
| Tag milestones | Team lead | Tag the version you present, for example v1.0-final-defense |
git switch main
git pull
git tag -a v1.0-final-defense -m "Version presented at final defense"
git push origin v1.0-final-defenseWrite a useful README
Your README is the first thing your adviser, panelists, and future maintainers see. It should let someone set up the project without asking you. Include these sections:
- Project title and summary: one paragraph on what the system does and for whom.
- Tech stack: language, framework, database, and versions.
- Requirements: what to install first, such as PHP, Composer, Node.js, or Flutter.
- Setup: step-by-step commands, including copying
.env.exampleand running migrations and seeders. - Default accounts: demo-only credentials for seeded test users, never real ones.
- Team: members and their roles.
- Licence or usage note: as agreed with your school and client.
Common mistakes to avoid
- Committing
.env, database dumps with real personal data, or API keys. - Committing
vendor/ornode_modules/, which bloats the repository. - Everyone working directly on
main. - Waiting until the week before the defense to merge everyone's work.
- Using
git push --forceon a shared branch, which can erase teammates' commits. - One member doing all the commits for the team, which hides who built what.
Next step
Before your next coding session, protect your main branch and have each member open one small pull request from a feature branch. Then agree on where files go, using the capstone folder structure guide.