Cornerstone + SVN 完整教程：从入门到精通

Cornerstone 是一款在 macOS 平台上非常流行的、功能强大的 SVN 客户端图形化工具，它将复杂的命令行操作转化为直观的拖拽和点击，极大地提高了团队协作和版本控制的效率。

目录

1. 第一部分：准备工作
   • 1 安装 Cornerstone
   • 2 获取 SVN 仓库地址
2. 第二部分：首次使用与仓库连接
   • 1 启动 Cornerstone 并配置身份
   • 2 连接 SVN 仓库（检出/Checkout）
3. 第三部分：核心日常操作
   • 1 更新/Update：获取最新代码
   • 2 添加/Add：将新文件纳入版本控制
   • 3 修改与提交/Commit：保存你的工作
   • 4 查看差异/Diff：对比文件变更
   • 5 解决冲突/Resolve Conflicts
4. 第四部分：分支与标签管理
   • 1 创建分支
   • 2 切换分支
   • 3 合并分支
   • 4 创建标签
5. 第五部分：查看历史与版本回滚
   • 1 浏览项目历史
   • 2 查看特定文件的修改历史
   • 3 回滚文件到历史版本
6. 第六部分：高级技巧与最佳实践
   • 1 忽略文件（.gitignore 的 SVN 版本）
   • 2 使用外部差异工具（如 Kaleidoscope）
   • 3 常见问题与解决方案

第一部分：准备工作

在开始之前,请确保你已经具备以下条件：

1 安装 Cornerstone

1. 购买与下载：Cornerstone 是一款付费软件，你需要先到其官方网站 zennaware.com/cornerstone/ 购买许可证并下载安装包。
2. 安装：将下载的 .dmg 文件挂载，将 Cornerstone 拖拽到 Applications 文件夹即可。
3. 启动：首次启动时，会提示你输入购买时注册的邮箱和许可证密钥进行激活。

2 获取 SVN 仓库地址

你需要从你的 SVN 服务器管理员那里获取仓库的 URL，通常看起来像这样：

• http://svn.example.com/project/trunk
• https://svn.yourcompany.com/your-project
• svn+ssh://user@svn.example.com/project

这个 URL 是你连接到仓库的“门牌号”。

第二部分：首次使用与仓库连接

1 启动 Cornerstone 并配置身份

1. 打开 Cornerstone。
2. 点击菜单栏的 Cornerstone -> Preferences... (或使用快捷键 )。
3. 在弹出的偏好设置窗口中,选择 Accounts 标签页。
4. 点击左下角的 号，添加一个新的 SVN 账户。
   • Name：给这个账户起一个你自己的名字，方便识别（"公司 SVN"）。
   • URL：填入你从管理员那里获取的 SVN 仓库地址。
   • Authentication：根据你的服务器配置选择认证方式。
     • None：匿名访问（不常见）。
     • Username/Password：最常见的用户名密码登录。
     • SSH Key：如果你使用 SSH 密钥认证，需要配置好密钥并指定路径。
5. 填写完毕后,点击 Test Connection 确保可以成功连接到服务器，然后点击 Save。

2 连接 SVN 仓库（检出/Checkout）

“检出”操作相当于将远程仓库的完整副本下载到你的本地电脑上。

1. 在 Cornerstone 左侧的 Repositories 列表中，找到你刚刚添加的仓库账户，点击展开它。
2. 你会看到仓库的目录结构,通常包含 trunk（主干）、branches（分支）、tags（标签）等。
3. 找到你想要开发的工作目录（通常是 trunk），右键点击它，选择 Checkout...。
4. 在弹出的窗口中：
   • Local Path：选择一个本地文件夹来存放项目代码，建议选择一个你容易找到的位置，如 ~/Documents/Projects/MyProject。
   • Options：可以保持默认。
5. 点击 Checkout，Cornerstone 会开始从服务器下载所有文件和版本历史，下载完成后，你选定的本地路径就会被添加到左侧的 Working Copies 列表中。

第三部分：核心日常操作

假设你已经成功检出了一个项目,现在开始日常开发。

1 更新/Update：获取最新代码

在开始你的工作之前,强烈建议先执行更新，以确保你是在最新的代码基础上进行修改，避免不必要的冲突。

1. 在左侧 Working Copies 中，右键点击你的本地项目。
2. 选择 Update，或者直接在项目文件列表的空白处右键选择 Update。
3. Cornerstone 会从服务器拉取所有最新的更改并合并到你的本地副本。

2 添加/Add：将新文件纳入版本控制

当你创建了新的文件或文件夹（如一个新功能的源代码文件），SVN 默认不会跟踪它，你需要手动将其“添加”到版本控制中。

1. 在 Finder 中，将新文件/文件夹复制到你项目的本地文件夹中。
2. 切换回 Cornerstone，你会看到左侧的文件列表中出现了新文件，并且它的状态是 (未版本控制)。
3. 选中这个新文件,右键点击，选择 Add，或者直接拖拽文件到右下角的 Incoming 或 Outgoing 区域，Cornerstone 会提示你添加。
4. 文件的状态会变为 A (已添加)，但这只是暂存，下一步才是真正提交。

3 修改与提交/Commit：保存你的工作

这是最核心的操作,将你的修改“上传”到服务器。

1. 修改文件：在 Cornerstone 中双击文件（如果配置了关联的编辑器）或在 Finder 中用你喜欢的编辑器修改文件。
2. 查看修改：回到 Cornerstone，你会看到被修改的文件状态变为 M (已修改)。
3. 准备提交：
   • 方法一（推荐）：在文件列表的空白处右键，选择 Commit...。
   • 方法二：直接拖拽所有状态为 M 或 A 的文件到右下角的 Outgoing 区域。
4. 填写提交信息：
   • 在弹出的 Commit 窗口中，左侧会列出你即将提交的文件。
   • 在右侧的 Message 框中，清晰、简洁地描述你这次做了什么修改。"feat: 添加用户登录功能" 或 "fix: 修复了首页按钮样式问题"，好的提交信息对团队协作至关重要。
5. 提交：点击 Commit 按钮，Cornerstone 会将你的修改发送到服务器，完成后，文件状态会恢复为空白（表示本地与服务器同步）。

4 查看差异/Diff：对比文件变更

在提交之前,你想看看具体修改了什么内容？

1. 在文件列表中,右键点击一个状态为 M 的文件。
2. 选择 Diff。
3. Cornerstone 会打开一个对比窗口，左边是你的本地修改版本，右边是服务器上的最新版本，所有增删改的地方都会用不同颜色高亮标记，非常直观。

5 解决冲突/Resolve Conflicts

当两个人同时修改了同一个文件的同一行时,其中一个人先提交成功，另一个人在提交时就会遇到冲突。

1. 冲突发生：当你尝试提交一个与他人修改过的文件时，提交会失败，Cornerstone 会提示你存在冲突。
2. 标记冲突：回到 Cornerstone，你会看到冲突的文件状态变为 C (Conflict)。
3. 解决冲突：
   • 双击冲突文件,Cornerstone 会打开一个 3-way Merge Editor（三路合并编辑器）。
   • 这个编辑器会清晰地展示：
     • Yours：你的本地修改。
     • Theirs：别人的修改。
     • Base：你们共同的祖先版本。
   • 你需要仔细审查,手动决定保留哪些修改，删除哪些修改，或者如何将两者融合，编辑器通常会提供合并工具帮助你。
4. 标记为已解决：当你手动编辑完文件，解决了所有冲突后，必须告诉 SVN“冲突已经解决”。
   • 在 Cornerstone 中，右键点击该文件，选择 Mark as Resolved。
5. 再次提交：现在文件状态变为 M (已修改)，你可以再次执行 Commit 操作，将解决冲突后的版本提交到服务器。

第四部分：分支与标签管理

1 创建分支

分支用于开发独立的功能或修复 Bug，不会影响主分支。

1. 在左侧 Repositories 中，找到你的仓库。
2. 右键点击 trunk (或你希望基于哪个版本创建分支)，选择 Branch...。
3. 在弹出的窗口中：
   • To Path：输入新分支的路径，branches/new-feature-user-profile。
   • From Path / Revision：选择你要基于的源路径和版本（通常是 trunk 的最新版本）。
   • Create Copy：确保勾选此项。
4. 点击 Branch，分支就在服务器上创建好了。

2 切换分支

你想在另一个分支上工作？

1. 在左侧 Working Copies 中，右键点击你的本地项目。
2. 选择 Switch...。
3. 在弹出的窗口中：
   • To URL：输入你想要切换到的分支 URL，http://svn.example.com/project/branches/new-feature-user-profile。
4. 点击 Switch，Cornerstone 会将你的本地工作目录“切换”到新的分支，下载该分支的文件，完成后，你就可以在这个分支上开发了。

3 合并分支

当新功能开发完成,需要合并回 trunk 时。

1. 确保你当前在 trunk 分支上：通过 Switch 切换到 trunk。
2. 右键点击你的本地项目,选择 Merge...。
3. 在合并向导中：
   • From：选择要合并的源分支 URL (branches/new-feature-user-profile)。
   • To：选择合并的目标 URL (通常是 trunk)。
   • Range：选择合并整个分支的修改。
4. 按照向导提示完成操作,合并后，trunk 的文件会被修改，你需要像往常一样 Commit 这次合并。

4 创建标签

标签用于为项目的重要版本（如 V1.0, V2.1）创建一个“快照”。

1. 操作与创建分支几乎完全相同。
2. 在 Repositories 中，右键点击 trunk (或任何你想要打标签的路径)，选择 Branch...。
3. To Path：输入标签路径，tags/v1.0-final。
4. 关键区别：创建标签后，绝对不要在标签目录下进行任何修改或提交，它只是一个只读的副本。

第五部分：查看历史与版本回滚

1 浏览项目历史

1. 在 Repositories 中，右键点击一个文件夹或文件，选择 Browse Repository。
2. 这会打开一个浏览器窗口,你可以像在 Finder 中一样浏览仓库的整个历史版本，并查看每个版本是谁提交的、提交了什么。

2 查看特定文件的修改历史

1. 在 Working Copies 或 Repository Browser 中，右键点击一个文件。
2. 选择 Show Log。
3. 你会看到一个时间线,列出了该文件的所有修改记录，你可以点击任意一个记录，查看当时的详细信息。

3 回滚文件到历史版本

如果你不小心提交了错误的代码,需要将某个文件恢复到之前的版本。

1. 在 Show Log 窗口中，找到你想要回滚到的那个历史版本记录。
2. 右键点击该记录,选择 Update Working Copy to Revision...。
3. 在弹出的窗口中,选择 This item only (仅此文件) 或 This item and all children (此文件及其子目录)。
4. 点击 Update，Cornerstone 会将你的本地文件替换为历史版本。
5. 文件状态变为 M，你需要 Commit 这次“回滚”操作，将正确的版本覆盖掉错误的版本。

第六部分：高级技巧与最佳实践

1 忽略文件

有些文件不需要纳入版本控制,如编译产物、本地配置文件、IDE 缓存等。

1. 在 Working Copies 中，右键点击你的项目。

2. 选择 Reveal in Finder。

3. 在项目根目录下,创建一个名为 svn:ignore 的无扩展名文件。

4. 用文本编辑器打开它,在每一行写入你想要忽略的文件或文件夹模式，格式同 .gitignore。

   # 忽略所有 .log 文件
   *.log
   # 忽略 dist 文件夹
   /dist/
   # 忽略 IDEA 项目配置文件
   .idea/

5. 保存文件后,回到 Cornerstone，你会看到 svn:ignore 文件本身的状态是 ，右键点击它，选择 Add，Commit，这样，所有匹配这些模式的文件和文件夹就都会被 SVN 忽略了。

2 使用外部差异工具

Cornerstone 自带的差异工具不错，但如果你更喜欢 Kaleidoscope、Araxis Merge 或 Beyond Compare，可以配置 Cornerstone 调用它们。

1. 打开 Cornerstone -> Preferences...。
2. 选择 Diff/Merge 标签页。
3. 在 External Diff Tool 下拉菜单中，选择你已安装的工具，如果列表中没有，可以点击 Choose... 手动指定应用程序。

3 常见问题与解决方案

• 问题：提交时提示 "Aborting commit: '/path/to/file' remains in conflict" 解决：说明你还有文件未解决冲突，找到状态为 C 的文件，Mark as Resolved 后再提交。
• 问题：更新或提交时提示 "Entry's schedule add ... is missing or invalid" 解决：通常是文件名包含中文或特殊字符，导致 SVN 无法正确处理，建议使用英文命名文件和文件夹。
• 问题：如何删除一个文件或文件夹？ 解决：在 Cornerstone 中右键点击要删除的文件/文件夹，选择 Delete，这会将其从版本控制中移除，提交后，其他成员更新也会被删除。

通过这份教程,你应该已经掌握了 Cornerstone 的核心用法，能够独立完成日常的 SVN 版本控制操作。

核心工作流回顾：

1. 更新：Update -> 获取最新代码。
2. 开发：修改文件、Add 新文件。
3. 检查：使用 Diff 查看修改。
4. 提交：Commit 并填写清晰的提交信息。
5. 冲突：遇到 Conflict 时，手动解决并 Mark as Resolved。

SVN 和 Cornerstone 是强大的工具，遵循良好的工作流程（如频繁更新、清晰的提交信息、及时解决冲突）能让你的团队协作更加顺畅高效，祝你使用愉快！