Cornerstone 使用教程

什么是 Cornerstone？

Cornerstone 是一款专为 macOS 设计的 Git 图形化客户端，它将复杂的 Git 命令行操作转化为直观的拖拽、点击和右键菜单，极大地降低了 Git 的使用门槛，让开发者可以更专注于代码本身,而不是命令行的繁琐。

核心优势：

• 图形化操作：可视化地查看文件状态、差异、历史记录。
• 直观的合并工具：提供强大的三向合并工具,解决冲突变得简单。
• 良好的集成：与 Xcode、SourceTree 等工具有良好的协作。
• 功能全面：覆盖了日常开发中 99% 的 Git 操作。

安装与初始设置

1. 下载与安装

   • 访问官方网址：https://www.zennova.cc/cornerstone/
   • 下载适用于 macOS 的最新版本。
   • 将下载的 .dmg 文件挂载，将 Cornerstone 拖拽到 Applications 文件夹即可。

2. 首次启动与配置

   • 首次打开 Cornerstone,它会引导你进行一些基本设置。
   • 配置全局用户信息：输入你在 Git 上的用户名和邮箱，这非常重要，因为每次提交都会记录这些信息。
     • 菜单栏 Cornerstone -> Preferences... -> Git -> User
     • 设置你的 Name 和 Email。
   • 克隆或创建仓库：
     • 克隆现有仓库：File -> Clone Repository...，输入仓库的 URL,选择本地存储位置。
     • 创建本地仓库：File -> New Repository...,选择一个空文件夹作为仓库根目录。

界面概览

熟悉界面是高效使用的第一步，Cornerstone 的主界面通常分为几个关键区域：

1. 工具栏：包含最常用的操作，如提交、拉取、推送、同步等。
2. 文件浏览器：左侧区域,显示你本地仓库的文件和文件夹结构。
3. 状态列表：中间区域，根据所选操作（如“未提交更改”、“已拉取的更改”）显示文件列表。
4. 内容/差异视图：右侧区域,显示文件的详细内容或差异对比。
5. 仓库导航器：左上角,可以快速在不同仓库之间切换。

核心工作流程

这是最常用、最核心的操作流程,我们将围绕它展开详细讲解。

从远程仓库获取最新代码 (Pull)

在你开始工作前，务必先获取最新的远程代码,以避免冲突。

• 操作方式：
  1. 确保你选择的分支是正确的（main 或 develop）。
  2. 点击工具栏的 “Pull” 按钮（或按 ⌘+U）。
  3. Cornerstone 会显示一个确认对话框，告诉你将要拉取的分支和提交信息,确认即可。
• 作用：将远程仓库的更新合并到你的本地当前分支。

修改文件并提交更改

这是你日常编码的主要工作。

• 操作方式：
  1. 使用你喜欢的编辑器（如 VS Code, Xcode）修改项目中的文件。
  2. 切换回 Cornerstone，你会看到文件浏览器中，被修改的文件会以 蓝色 标记。
  3. 暂存更改：
     • 方式一（推荐）：在文件浏览器中，右键点击你想要提交的文件或文件夹，选择 "Stage" (暂存)，暂存的文件会变成 绿色。
     • 方式二：在“未提交更改”视图中,勾选文件左侧的复选框。
  4. 提交更改：
     • 在下方的提交信息输入框中，清晰、简洁地描述你这次做了什么（“feat: 添加用户登录功能”）。
     • 点击工具栏的 “Commit” 按钮（或按 ⌘+Enter）。
• 作用：将你的修改保存到本地仓库，这是一个“快照”,记录了某个时刻的项目状态。

推送你的提交到远程仓库 (Push)

当你完成了本地的工作,需要将提交分享给团队。

• 操作方式：
  1. 确保你已经提交了所有更改。
  2. 点击工具栏的 “Push” 按钮（或按 ⌘+P）。
  3. Cornerstone 会显示一个对话框，列出你本地有但远程没有的提交，确认后点击 "Push"。
• 作用：将你的本地提交上传到远程仓库,供其他协作者拉取。

分支操作

分支是 Git 的核心功能，用于开发新功能、修复 Bug 等。

• 创建新分支：
  • 在仓库导航器或分支列表中,右键点击当前分支。
  • 选择 "Create Branch..."。
  • 输入新分支名称，并选择从哪个分支创建（通常是当前分支）。
  • 创建后,切换到新分支开始工作。
• 切换分支：

  在仓库导航器或分支列表中,直接点击你想要切换到的分支即可。

• 合并分支：
  • 假设你在 feature/new-login 分支上完成了开发，现在要把它合并到 main 分支。
  • 切换到 main 分支。
  • 右键点击 feature/new-login 分支，选择 "Merge into 'main'"。
  • Cornerstone 会打开合并工具,确认合并信息后完成合并。

解决合并冲突

当多人修改了同一文件的同一部分时，合并时就会产生冲突，Cornerstone 提供了可视化的工具来解决它。

• 冲突发生时：
  1. 在合并或拉取操作后，有冲突的文件会以 黄色 和红色标记显示。
  2. 双击该文件，Cornerstone 会打开 合并工具。
• 使用合并工具：
  • 合并工具通常分为三列：
    • 左侧：你的版本（当前分支的修改）。
    • 中间：最终结果（你需要编辑的地方）。
    • 右侧：他人的版本（要合并进来的分支的修改）。
  • 你可以通过点击上方的按钮来决定如何解决冲突：
    • 保留我的：使用左侧的版本。
    • 保留他们的：使用右侧的版本。
    • 保留两者：将左右两边的代码都保留到中间,你需要手动编辑。
  • 解决完所有冲突后，中间的编辑器会像一个普通的文本编辑器。记得保存文件。
  • 回到 Cornerstone 主界面，你会看到这个冲突文件已经变成了 绿色（被暂存）。
  • 提交这次合并：填写提交信息（"Merge branch 'feature/new-login'"），然后点击 Commit,冲突解决完毕！

其他常用功能

1. 查看历史记录

   • 在文件浏览器中右键点击一个文件或文件夹，选择 "Show Log"。
   • 你会看到一个时间线，展示了该文件的所有提交记录，可以点击每一条记录，查看具体的修改内容（diff）。

2. 比较差异

   • 比较两个版本：在历史记录窗口中，按住 Command 键点击两个提交记录，然后右键选择 "Compare Selected"。
   • 比较工作目录和暂存区：在“未提交更改”视图中，选中文件,右侧会直接显示你的修改。
3. • 用于给重要的提交打上标记，如 v1.0.0。
   • 在历史记录窗口中右键点击一个提交，选择 "Tag This Commit..."。

4. 忽略文件

   • 有些文件（如编译产物、日志、IDE 配置文件）不需要被 Git 追踪。
   • 在文件浏览器中右键点击文件或文件夹，选择 "Ignore"，这会在 .gitignore 文件中添加相应规则。

进阶技巧与最佳实践

• 善用快捷键：⌘+U (Pull), ⌘+P (Push), ⌘+Enter (Commit) 等,能大幅提升效率。
• 保持提交的原子性：一次提交只做一件事，不要把“修复 Bug”和“添加新功能”混在同一个提交里。
• 写好提交信息：遵循清晰的格式，如 类型(范围): 描述。feat(auth): 添加第三方登录支持。
• 定期 Pull：养成开始工作前先 Pull 的好习惯,减少冲突的发生。
• 使用分支：为每个新功能或 Bug Fix 创建独立的分支，开发完成后再合并,这能保持主分支的整洁稳定。

常见问题与解决方案

• Q: Cornerstone 提示 "Authentication failed" 怎么办？

  • A: 这通常是因为你的远程仓库（如 GitHub, GitLab, Bitbucket）需要身份验证。
    • HTTPS: 在 Cornerstone -> Preferences... -> Accounts 中添加你的账户，输入用户名和密码（或 Personal Access Token）。
    • SSH: 确保你的 SSH Key 已经添加到你的 Git 账户，并且在 Cornerstone 的账户设置中选择了 SSH 方式。

• Q: 我想撤销一次本地的提交，怎么办？

  • A:
    • 撤销提交但保留修改：在“未提交更改”视图中，右键点击提交记录，选择 "Uncommit",这次提交的修改会变回未提交状态。
    • 彻底删除提交：在历史记录中右键点击该提交，选择 "Reset This Commit..."。警告： 这会修改历史，请确保你的提交已经推送到远程,或者只在本地分支上操作。

• Q: 如何删除远程分支？

  • A: 在分支列表中，右键点击远程分支，选择 "Delete Remote Branch..."。

Cornerstone 是一个非常优秀的 Git GUI 工具，它将 Git 的强大功能以一种优雅、直观的方式呈现出来，通过本教程的学习，你应该已经掌握了它的核心操作，多加练习,你很快就会发现它能让你的版本控制工作变得轻松愉快。

推荐路径：

1. 从 Clone -> Pull -> Edit -> Stage -> Commit -> Push 这个主流程开始。
2. 熟练后，尝试使用 分支 来管理不同的开发任务。
3. 学习如何使用 合并工具 解决冲突。

祝你使用愉快！