XHGit · 产品文档

Git 与代码操作

克隆、推送、分支、提交、标签、SSH、LFS 和在线编辑。

01

阅读导览

Git 在本地保存代码历史,XHGit 保存远程仓库并提供协作界面。下面以测试地址和占位身份演示;实际地址应从仓库“代码”菜单复制,包含站点当前的协议、域名和 SSH 端口。命令中的示例值都需要替换。

02

配置身份并克隆仓库

  1. 在电脑安装 Git,打开终端执行 git --version 确认可用。
  2. 设置提交身份。邮箱应选择自己的已验证邮箱,或个人设置显示的隐私提交邮箱。
  3. 从仓库复制 HTTPS 或 SSH 地址,再执行克隆。
git config --global user.name "Example Developer"
git config --global user.email "developer@example.test"
git clone https://git.example.test/team/demo.git
cd demo
git remote -v

身份配置决定提交作者信息,不能替代远程认证。克隆私有仓库时,还需要对应账号的读取权限。

03

配置 SSH 或 HTTPS 认证

SSH 方式可用 ssh-keygen -t ed25519 -C "developer@example.test" 生成密钥,在密钥设置添加 .pub 公钥。保管私钥和口令,不要把私钥提交到仓库或上传到聊天。

HTTPS 方式按客户端提示输入账号及适用的访问令牌,使用系统凭据管理器保存。双重验证、站点认证策略或令牌范围可能限制密码认证。不要把令牌拼进远程 URL,它会进入终端历史和 Git 配置。克隆成功后可在账号与安全继续检查凭据。

04

在功能分支完成一次提交

  1. 确认工作区状态,从目标分支创建功能分支。
  2. 修改文件,检查差异,再暂存明确需要提交的文件。
  3. 写有意义的提交说明,推送新分支。
git switch -c docs/quick-start
git status
git diff
git add README.md
git commit -m "docs: improve quick start"
git push -u origin docs/quick-start

推送只会更新远程分支;是否进入主分支,要看你推送的目标和仓库保护规则。团队项目建议继续创建合并请求。

05

把现有本地项目上传到空仓库

  1. 在 XHGit 创建空仓库,不选择初始化文件,避免两边各自产生独立首提交。
  2. 在本地项目目录检查 .gitignore,排除构建缓存、私钥和环境配置。
  3. 如果尚未初始化,执行 git init,提交文件,再添加远程地址并推送当前分支。
git init
git switch -c main
git add README.md
git commit -m "docs: add project introduction"
git remote add origin https://git.example.test/team/demo.git
git push -u origin main

已有 origin 时先执行 git remote -v,按真实情况调整,不能反复添加同名远程。不要把 git add . 当作无需检查的默认步骤。

06

同步远程变更并处理冲突

  1. 用 git status 确保本地修改已提交或妥善保存。
  2. 先 git fetch origin 获取远程信息,再选择合并或变基策略;不确定时使用团队约定。
  3. 冲突时逐个检查标记,保留正确内容,运行测试后继续提交或变基。

git pull --ff-only 可在分支能够直接快进时同步,出现分叉会停下让你决定。推送提示 non-fast-forward 时应先了解远程新提交,不要直接强推覆盖协作者的历史。主分支保护可能要求合并请求和检查通过,参见仓库管理。

07

大文件、标签和下载的区别

LFS 需要站点启用,并在开发设备安装客户端;用 .gitattributes 指定文件,再正常提交和推送。LFS 存储的是独立对象,普通仓库 ZIP 不一定符合你对完整工作副本的预期。

标签标记代码位置,可通过 git tag v0.1.0 和 git push origin v0.1.0 发布测试版本标签。标签本身不生成安装包;可下载的软件需要在发布上传附件,或通过自动构建生成产物。受保护标签会限制创建与删除权限。

08

失败时收集有用信息

认证失败先确认远程地址、账号权限和凭据类型;推送被拒绝检查分支保护、仓库归档、镜像状态和文件限制。记录 Git 原始错误,隐藏令牌与私有路径后交给维护者。下载 ZIP 只能得到一次代码快照,继续提交需要使用 git clone 创建带历史的工作副本。