Working with Git Repositories

Install Git

Download from git-scm.com and follow the installer for your operating system. Open a terminal and run git --version to confirm it is installed.

Identify yourself

Git records your name and email on every commit. Set them once with:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Use the same email you registered with your hosting provider (GitHub, GitLab, Gitea) so commits are attributed correctly.

Choose a hosting provider

Set up authentication

Use SSH keys or personal access tokens—never passwords. Generate an SSH key with ssh-keygen -t ed25519, then add the public key to your hosting provider settings. Test with ssh -T git@github.com (or your provider's equivalent).

Create your first repository

On the hosting site, create a new repository. Clone it to your computer:

git clone git@github.com:username/myproject.git
cd myproject

Start adding files, committing, and pushing. Your local folder is now connected to the shared remote.

Pull the latest changes

Before starting work, sync with the remote so you have the current code:

git checkout main
git pull origin main

Create a feature branch

Never work directly on main. Create a branch with a descriptive name:

git checkout -b feat/add-contact-form

Branch naming conventions: feat/ for features, fix/ for bug fixes, docs/ for documentation, refactor/ for internal improvements.

Make changes and commit

Stage the files you want to include, then commit with a clear message:

git add src/contact.html src/contact.css
git commit -m "Add contact form with validation"

Write commit messages in imperative mood: "Add contact form" not "Added contact form" or "adding contact form." The first line is under 72 characters; add detail on subsequent lines if needed.

Push and open a pull request

Upload your branch and create a PR for review:

git push origin feat/add-contact-form

Then open the PR on your hosting platform. Write a description: what changed, why, and how to test it. Attach screenshots for visual changes.

Address feedback and merge

Reviewers may request changes. Make the fixes, commit them to the same branch, and push. The PR updates automatically. Once approved and tests pass, merge the PR and delete the branch.

git checkout main
git pull origin main
git branch -d feat/add-contact-form

Fork the repository

On your hosting platform (GitHub, GitLab, Gitea), click the "Fork" button. This creates a copy under your account, for example your-username/project-name.

Clone your fork locally

git clone git@github.com:your-username/project-name.git
cd project-name

Your local clone has origin pointing to your fork, not the original.

Add the upstream remote

Connect your local clone to the original repository so you can pull in changes:

git remote add upstream git@github.com:original-owner/project-name.git
git remote -v

You now have two remotes: origin (your fork) and upstream (the original).

Sync your fork with upstream

Before starting work, pull the latest changes from the original project:

git fetch upstream
git checkout main
git merge upstream/main

This brings your local main up to date. Push to your fork to sync the remote copy:

git push origin main

Create a feature branch, commit, and push

git checkout -b feat/your-feature
# make changes, commit
git push origin feat/your-feature

Open a pull request from your fork

On your hosting platform, open a PR from your fork's branch to the original repository's main branch. The platform handles cross-repository PRs automatically.

Clone the source as a mirror

git clone --mirror git@github.com:original-owner/project-name.git

This creates a bare repository (no working directory) that contains every ref. The --mirror flag configures the remote to fetch all refs.

Push the mirror to the destination

cd project-name.git
git push --mirror git@gitea.example.com:your-account/project-name.git

The --mirror flag on push ensures all refs, including deleted ones, are replicated. Warning: this overwrites the destination. Use it only on empty or intended-to-be-replaced targets.

Keep the mirror in sync

Run this periodically (manually or via a cron job):

git fetch -p origin
git push --mirror git@gitea.example.com:your-account/project-name.git

The -p flag prunes refs that no longer exist on the source.

Read the contribution guidelines

Look for CONTRIBUTING.md, CONTRIBUTING.rst, or a "Contributing" section in the README.md. These guidelines tell you:

• What kinds of contributions are welcome (bug fixes, features, docs, translations)
• How to set up the development environment
• Coding style and conventions
• How to structure your commits and PRs
• Whether you need to open an issue before a PR

If there are no guidelines, look at recent PRs to understand the project's conventions.

Find or open an issue

Check the issue tracker for something you want to work on. If you have a new idea, open an issue first to discuss it with maintainers before writing code. This avoids wasted effort on changes the project may not want.

Fork and clone

git clone git@github.com:your-username/project-name.git
cd project-name
git remote add upstream git@github.com:original-owner/project-name.git

Set up the development environment

Follow the project's setup instructions. Install dependencies, configure linters, and make sure the test suite passes on the unmodified codebase before you start.

Create a focused branch

git checkout -b fix/issue-42-null-pointer

One branch per issue or feature. Keep the scope narrow. A PR that fixes one bug is easier to review than a PR that fixes five.

Make changes, test, and commit

Write the code, add or update tests, and run the full test suite. Commit with a message that references the issue:

git commit -m "Fix null pointer when user profile is empty

Closes #42"

Many platforms (GitHub, GitLab, Gitea) auto-close issues when a PR with this text merges.

Push and open a pull request

git push origin fix/issue-42-null-pointer

Open the PR from your fork to the original repo. In the description, explain what changed, why, and how to test it. Reference the issue number.

Respond to review feedback

Maintainers will review your PR. They may request changes, ask questions, or suggest alternatives. Respond promptly, make the requested changes, and push updates to the same branch. The PR updates automatically.

Create the organization

On your hosting provider, create an organization with a clear name that reflects your team or company. Invite founding members as owners so they can manage settings and billing. Keep the number of owners small (2-3) for security.

Define teams

Create teams that match how your group works: frontend, backend, devops, design, etc. Add members to the appropriate teams. Teams inherit repository access, so you manage permissions once instead of per-person per-repo.

Set default repository settings

Configure organization-level defaults so every new repository starts secure:

• Default branch: Set to main with protection rules.
• Require PR reviews: At least one approval before merging.
• Require status checks: CI must pass before merging.
• Restrict force pushes: Disable on protected branches.
• Require signed commits: Enable for high-security repos.

Create a template repository

Build a repo-template with your standard README.md, .gitignore, CONTRIBUTING.md, license file, and CI configuration. Enable it as a template so new projects start with consistent structure and tooling.

Document your conventions

Store team conventions in an ORG-CONVENTIONS.md or wiki: branch naming, commit message format, PR template, code style, release process, and on-call rotation. Link it from the organization profile so new members find it immediately.

Audit what you are moving

List all projects, estimate sizes, identify sensitive files (credentials, API keys, personal data), and note which projects have existing Git history versus flat file dumps. Check for large binary files that should go to a blob store instead of Git.

Clean the source

Remove credentials, secrets, and personal data before migration. Check for accidentally committed secrets using tools like git-secrets or trufflehog. If secrets are already in Git history, use git filter-repo to remove them before pushing to the new provider.

Set up the destination

Create the organization, teams, and repositories on the new provider before migrating. Configure branch protection, default permissions, and webhooks. Having the structure ready prevents ad-hoc access grants during the migration.

Branch protection

Enable on main and any release branches. Require at least one PR review, require status checks to pass, restrict who can push, and disable force pushes. This is your first line of defense against accidental or malicious changes.

Two-factor authentication (2FA)

Require 2FA for all organization members. Most providers let you enforce this at the organization level. Without 2FA, a compromised password gives full access to your code.

Secret scanning and push protection

Enable built-in secret scanning (GitHub, GitLab, and Gitea all offer this). It detects accidentally committed API keys, tokens, and passwords. Push protection blocks the commit before it reaches the repo. Review alerts weekly and rotate any exposed secrets immediately.

Access reviews

Run quarterly access reviews. Remove users who have left, downgrade permissions that are no longer needed, and revoke unused tokens. Most providers show a list of collaborators and their last activity—use it.

Audit logs

Enable and monitor audit logs. They record every login, permission change, branch protection modification, and repository deletion. Set up alerts for high-risk actions: new owners added, branch protection disabled, or repositories transferred. Review logs monthly for anomalies.

Does it do what the PR says?

Read the description, then skim the diff. Does the change match the stated intent? Is the scope reasonable, or has it crept beyond the original goal?

Is it correct?

Check for logic errors, null handling, error paths, and edge cases. Does the code handle failure gracefully, or does it crash silently?

Is it secure?

Look for unvalidated input, hardcoded secrets, excessive permissions, SQL injection, XSS, and data exposure. A change that introduces a vulnerability is not acceptable even if the feature works.

Is it testable?

Are there tests for the new behavior? Do existing tests still pass? If the change is untestable, flag it—untested code is untrusted code.

Is it maintainable?

Is the code readable and consistent with the project's style? Are complex functions broken into smaller pieces? Will the next person understand this in six months?