Before pushing code to a remote repository, let’s briefly understand “Why push?”: After you write and commit code locally, those changes only exist on your computer. To enable team collaboration, backup code, or host it on a remote platform (e.g., GitHub/GitLab), you need to “push” your local code to the remote repository.

I. Preparation Before Pushing¶

Ensure the following steps are completed before pushing:

1. Local Repository Contains Committed Code¶

Use git status to check the workspace status (confirm staged changes ready for commit), or directly use:

git add .  # Stage all changes
git commit -m "Commit message"  # Commit to local repository

Example:

git add .  # Stage all modified files
git commit -m "Add user login page code"  # Commit changes to local repo

2. Remote Repository Exists and Is Linked Locally¶

If you haven’t created a remote repository yet (e.g., create one on GitHub/GitLab), get its URL (usually https://github.com/your-username/your-repo.git or git@github.com:your-username/your-repo.git).
- If your local repo was cloned (e.g., git clone <remote-url>), it’s already linked to the remote repo (default alias: origin; verify with git remote -v).

II. Pushing Code to the Remote Repository¶

The core command is git push, but there are two scenarios: first-time push and subsequent pushes.

Scenario 1: First-Time Push (Local Branch Not Linked to Remote)¶

If this is the first time pushing a local branch to the remote repo (e.g., dev branch), explicitly specify the remote and branch names.

Syntax:

git push [remote-name] [local-branch]:[remote-branch]

• remote-name: Defaults to origin (clone default alias); use other names if specified.
• local-branch: Name of the local branch to push (e.g., dev).
• remote-branch: Name of the remote branch (optional; defaults to local branch name if omitted).

Example: Push local dev branch to remote dev branch (first push):

git push origin dev

Key: Add -u to auto-link local and remote branches (simplifies future pushes):

git push -u origin dev  # Links local dev to origin/dev

Scenario 2: Subsequent Pushes (Branch Already Linked)¶

If you used -u to link the branch earlier, just run git push to push the current branch to its associated remote branch.

Example:

git push  # Auto-pushes current branch to its remote (e.g., origin/dev)

If unlinked, explicitly specify:

git push origin <local-branch>  # e.g., git push origin master

III. Special Case: Different Local and Remote Branch Names¶

To push a local branch to a remote branch with a different name (e.g., local feature → remote new-feature):

git push origin feature:new-feature

IV. Verify After Pushing¶

Check the remote repository on GitHub/GitLab:
- Navigate to the repo → Switch branches → Confirm code is updated.

V. Common Issues & Solutions¶

1. Push Error: “Your local changes would be overwritten by merge”¶

• Cause: Remote repo has updates not pulled locally.
• Fix: Pull first, resolve conflicts, then push:

  git pull origin <branch-name>  # Fetch and merge remote changes
  # Resolve conflicts, then re-push

2. Push Error: “Permission denied”¶

• Cause: No push permissions (e.g., private repo without access) or incorrect credentials.
• Fix:
• Check repo permissions (ensure you’re a collaborator or owner).
• For HTTPS, re-enter credentials (GitHub/GitLab account password).

3. Undo a Mistaken Push¶

• If not pulled by others: Force push (use with caution!):

  git push --force origin <branch-name>  # Overwrites remote branch (only if safe)

• If pulled by others: Use git revert to undo the commit (not recommended force push):

  git revert <commit-hash>  # Creates a new commit to undo changes
  git push origin <branch-name>

Summary¶

The core workflow for pushing is: Prepare commits → Link branches (first push) → Run git push. Practice git push origin <branch> and git push -u origin <branch> to master it. Always pull latest code, check permissions, and ensure no uncommitted changes before pushing!