Remote collaboration with Git: fetching, tracking, and two remotes

"In a distributed version control system, a 'remote' is simply someone else's 'local'. Synchronization is, at its core, the alignment of two databases."

1. Establishing a Connection: What a Remote Really Is#

A remote typically uses a bare repository without a working tree, but it can also point to another local or server-side repository. Above all, a “remote” is a configured address and refspec. Before synchronizing, establish the "contract" between your local repository and the remote.

Basic Connection Commands (Common to All Protocols)

The following operations apply regardless of which protocol you choose:

# 1. 关联远程仓库 (通常命名为 origin)
git remote add origin <URL>

# 2. 查看已关联的远程及其 URL
git remote -v

# 3. 首次推送并建立追踪关系 (-u / --set-upstream)
git push -u origin master

# 4. 修改远程仓库地址 (例如从 HTTPS 切换到 SSH)
git remote set-url origin git@example.com:team/project.git

2. Three Ways to Authenticate with GitHub: Setup and Platform Differences#

A. HTTPS: Simple, but Requires Credential Management

• Address format: https://example.com/team/project.git
• Mechanism: use a PAT, OAuth credentials managed by a credential helper, or other supported credentials. Never put tokens in a remote URL or public configuration.
• Platform-Specific Setup:
  • Windows: Git for Windows includes Git Credential Manager, which handles OAuth pop-up windows automatically.
  • Arch Linux: use an actual Git credential helper and configure its secure storage backend. git-delta displays diffs; it does not store credentials.
  • NixOS: programs.git.enable = true; enables Git, but does not automatically set up HTTPS credential storage. Configure a credential helper separately.

B. SSH: Asymmetric Encryption for Professional Development (Recommended)

• Address format: git@example.com:team/project.git
• Mechanism: authenticate with an Ed25519 or RSA public/private key pair. You can protect the private key with a passphrase and use an agent; avoiding an account-password prompt does not mean the private key has no passphrase.
• Platform-Specific Setup and Key Generation:

  • Key-generation command for all platforms:

    EXCERPTCopy code

    ssh-keygen -t ed25519 -C "user@example.com"
    # 生成后将 ~/.ssh/id_ed25519.pub 内容贴到 GitHub Settings -> SSH Keys

  • Windows: run the command above in Git Bash. Keys are stored in %USERPROFILE%\.ssh\.

  • Arch Linux: install openssh. sudo pacman -S openssh

  • NixOS: the SSH client connects to Git servers. Outbound Git access does not require enabling services.openssh.enable, which starts the local SSH server. Configure the client and agent as needed.

C. GitHub CLI (gh): A Modern, One-Step Experience

• Tool: the official command-line tool combining Git operations with GitHub management features.
• Installation by Platform:
  • Windows: winget install --id GitHub.cli or scoop install gh.
  • Arch Linux: sudo pacman -S github-cli.
  • NixOS: environment.systemPackages = [ pkgs.github-cli ];.
• Core operations:

gh auth login  # 按交互选项授权；Git 凭据配置取决于选择，也可检查 gh auth setup-git
gh repo clone user/repo  # 一键克隆
gh repo set-default user/repo # 关联当前目录到 GitHub
    ```

## 3. 同步三剑客：Fetch, Pull, Push

| 命令 | 行为 | 哲学 |
| :--- | :--- | :--- |
| **`git fetch`** | 下载远程对象和指针 | **只看不拿**：了解进展，不改动本地代码。 |
| **`git pull`** | `fetch` + 按参数/配置合并或变基 | **同步更新**：直接把别人的改动合入当前分支。 |
| **`git push`** | 上传本地 Commit | **发布成果**：将你的快照同步到远程数据库。 |

> 现代推荐写法
> 若只接受快进，使用 `git pull --ff-only`；需要重放未共享的本地提交时，可按团队策略使用 `git pull --rebase`。它会改写本地提交，可能逐次产生冲突，不是所有分支的默认答案。

## 4. 追踪分支与 Upstream

当你看到 "Your branch is ahead of 'origin/master'" 时，Git 正在对比。
- **Upstream (上游)**：本地分支对应的远程 " 锚点 "。
- **手动关联**：`git branch --set-upstream-to=origin/master`。
- **意义**：关联后，只需输入 `git pull`，无需再写长串的远程名。

### 远端默认分支的符号引用

用 `git branch -r` 查看远端跟踪分支时，可能看到 `fork/HEAD -> fork/main`。这里 `fork` 是远端别名，`fork/HEAD` 是指向默认分支的符号引用，不是额外的开发分支，统计分支数时不能把它算进去。可分别检查本地分支的追踪关系和这个符号引用：

```powershell
git branch -vv
git branch -r
git symbolic-ref refs/remotes/fork/HEAD

If fork/HEAD has not been set locally, the last command fails; that does not mean fork/main is absent. When the remote's default branch changes, use git remote set-head fork -a to query the remote and update the local default-branch reference. See the official git remote documentation.

5. Collaborative Workflows: The PR / MR Model#

1. Fork: clone someone else's repository into your own account through the web interface.
2. Clone: use git clone to get a local copy.
3. Develop: create a new branch for development.
4. Push: push to your own remote.
5. Pull Request (PR): use the web interface to ask the original author to merge your changes.

5.1 Two-Remote Example: origin for the Original Repository, fork for Your Repository

origin, fork, and upstream are merely local aliases with no special privileges in Git. URLs determine which repository is read from or pushed to, and the server controls permissions. The GitHub Contribution Workflow uses upstream for the original repository and origin for the personal fork. The following is another equally valid configuration; confirm which convention you use before running commands.

Consider a fictional project. The example.com addresses below cannot connect to a real repository. The target configuration is:

origin  https://example.com/upstream/project.git
fork    https://example.com/contributor/project.git

Inspect the current configuration first, and add a remote only if its name does not already exist:

git remote -v
git remote add origin https://example.com/upstream/project.git
git remote add fork https://example.com/contributor/project.git

If cloning left origin pointing to your personal fork and no remote named fork exists yet, use these configuration steps instead:

git remote rename origin fork
git remote add origin https://example.com/upstream/project.git
git remote -v

Push your development branch to your personal fork and establish tracking:

# 将占位符替换为实际分支名
git push -u fork <branch>
git branch -vv

5.2 Three Distinct Kinds of Synchronization: References, Local main, and Fork main

Refresh remote-tracking references for every remote:

git fetch --all --prune

With a typical fetch configuration, this updates origin/* and fork/* and prunes stale tracking references for branches deleted remotely. It does not overwrite your local development branches with remote content. The fetch scope still depends on each remote's refspec and skip settings; a narrowly scoped clone does not automatically become an all-branch fetch. The official git fetch documentation explains --all, --prune, and refspecs.

To synchronize your local main with the original repository, check the working tree first, then allow only a fast-forward update:

git status --short
git switch main
git pull --ff-only origin main

If there are uncommitted changes, save and handle them appropriately before switching branches. If the histories have diverged, --ff-only refuses the update; inspect the unique commits before deciding how to preserve them.

To synchronize your personal fork's main, you can push the freshly fetched origin/main directly to the remote's main:

git fetch origin --prune
git push fork origin/main:main

origin/main:main means "use the local tracking reference for the original repository as the source to update the fork's main." This step does not require your local main to be synchronized, and it does not update other development branches in the fork. If the fork's main has diverged or branch protection restricts it, a normal push is rejected. Do not switch to a force push to conceal the divergence.

The complete routine for updating references, local main, and fork main together is therefore:

git status --short
git fetch --all --prune
git switch main
git pull --ff-only origin main
git push fork origin/main:main

Check each result, and resolve any failure before moving on. "Full synchronization" here does not mean forcibly resetting every development branch to the original repository's main. Preserve contribution commits that have not yet been merged.

5.3 Synchronizing and Comparing a Single Fork Branch

If the local branch already exists, fast-forward it from the fork:

git switch fix/review-feedback
git pull --ff-only fork fix/review-feedback

If the branch does not yet exist locally, fetch first, then create a tracking branch with the same name:

git fetch fork
git switch --track -c fix/review-feedback fork/fix/review-feedback

Before comparing a fork branch with the original repository's main, explicitly fetch both remotes:

git fetch --multiple --prune origin fork
git rev-list --left-right --count origin/main...fork/fix/review-feedback
git log --left-right --cherry-pick --oneline origin/main...fork/fix/review-feedback

Do not write git fetch origin fork --prune: the single-remote syntax interprets fork as a refspec to fetch from origin, not as a second remote. Use --multiple for multiple remotes, or run fetch separately for each.

In the output of rev-list, the left number counts commits unique to origin/main, and the right number counts commits unique to the fork branch. log distinguishes the two sides with < and >, while --cherry-pick excludes commits with equivalent patches on both sides. Its line count therefore may not match the preceding counts.

5.4 Development-Branch Count Is Not Open-PR Count

These three development branches correspond to only two open PRs. A merged branch may remain in the fork, and fork/HEAD should not be counted as a fourth development branch. Before cleaning up, check current PR status, the merge method, and whether unique commits remain. Do not delete branches based on their count alone.

6. Common Pain Points and Best Practices: Resolving Conflicts Gracefully#

Scenario: A Push Fails Because Multiple People Modified the Same Remote Branch

The following approach is suitable for local commits that have not yet been shared. For shared history, use merge or another coordinated approach according to team policy:

1. git commit (save local changes).
2. git fetch origin (retrieve the latest remote snapshot).
3. git rebase origin/master (replay local commits on top of the remote history).
4. Review the rebase result and run tests, then git push. Further remote updates or protection rules may still cause rejection.

A Closer Look: Why Can git push -f Be Disastrous?

When you run git push -f, you are effectively telling the server: "Ignore what everyone else committed and forcibly replace the remote branch with my current state."

Example scenario:

1. Shared starting point: you and colleague A both have Commit 1 -> Commit 2.
2. Colleague A commits: they develop a feature and push, so the remote is now 1 -> 2 -> 3.
3. You rewrite history: you decide the local Commit 2 could be better and modify it with rebase or amend. Your local history becomes 1 -> 2'(新哈希).
4. You run Push -f: you forcibly change the server's history to 1 -> 2'. Colleague A's Commit 3 disappears from the remote!
5. Disaster Strikes: when colleague A synchronizes again, their local and remote histories may diverge, requiring reconciliation with the rewritten history. Git finds that:
   • The local Commit 3 is based on the old Commit 2.
   • But the remote now has 2'.
   • This can lead to extremely complex conflicts. If they handle them incorrectly, for example by merging directly, they may bring back old code you had removed and even turn the project's entire history topology into a tangled mess.

Coordinate any rewriting of shared-branch history in advance, and check the server's protection rules. Do not conceal an ordinary synchronization failure with a force push.

A Safer Approach: --force-with-lease

If you must force-push, for example on your own isolated feature branch, use: git push --force-with-lease Mechanism: it requires the remote reference to match an expected value. Without an explicit expected value, it usually relies on the local remote-tracking reference. Background fetches may refresh that reference and weaken the protection. When strict constraints are needed, first record and verify the tip you are allowed to replace, then explicitly specify the remote branch and expected commit:

# 仅在已协调历史改写且确认目标分支允许时；两个占位符需实际核对
git push --force-with-lease=refs/heads/feature/example:<expected-tip> origin HEAD:refs/heads/feature/example

A lease cannot determine whether overwritten commits are valuable, nor can it automatically recover accidentally deleted data.

7. Permission Management: Who Can Push Code?#

Distributed history does not itself grant write access to remotes. Servers can control reads and pushes through SSH/HTTP authentication, filesystem permissions, receive hooks, and hosting-platform rules. Permission control is not exclusive to hosting platforms.

A. Repository Access Levels (Using GitHub as an Example)

1. Public: anyone can read (Clone/Fetch), but only "collaborators" can write (Push).
2. Private: access can be granted through individuals, organization teams, apps, deployment credentials, and other mechanisms, with read and write permissions controlled separately.
3. Collaboration Roles:
   • Read: can read and participate in relevant discussions, but generally cannot push code.
   • Write: can push code directly to unprotected branches.
   • Maintain/Admin: maintainer and administrator permissions differ. Sensitive settings, such as deleting a repository, typically require administrator privileges; verify the platform's role definitions.

B. Branch Protection Rules (Protected Branches)

On a professional team, having "write access" does not mean you can do anything you please.

• Restrict direct pushes: teams typically lock down main or master, preventing anyone from using push directly.
• Require Pull Requests: all code must be developed on a branch -> submitted as a PR -> merged by someone with the appropriate merge permissions after the required reviews and automated checks pass.
• Restrict force pushes: push -f is disabled on protected branches by default.

A Philosophical Note The highest purpose of permission management is to prevent mistakes, not merely to deter bad actors. Good rules let team members experiment freely on feature branches without breaking the mainline code.