HbGitHubBasic

ishanshan edited this page Apr 28, 2018 · 11 revisions

第一级:存活 | 安人集团简明 GitHub 练级攻略

了解了 GitHub 世界的基础概念、做好行前准备,是时候来操练一下,完成存活挑战。

在安人集团日常协作和开智课程中,无论是文档管理还是作业提交,都需你把对应的文本信息,更新到相应 GitHub 仓库的合适位置——要想存活,你得先懂如何在网页上完成常规文档的增删改查。再知道如何快速找到要用的仓库、资料,便不易迷失。如果再懂怎么知悉队友的动态及时响应,活下来就不是问题啦!

攻略直达通道:

注意:以下操作都需在完成 练级准备 后进行。

能在 GitHub 网页上完成常规操作

增删改文档

GitHub 仓库如云盘一样可以存放所有类型的文件,也如云盘一样只能预览及在线编辑部分类型的文件。

先熟悉一下修改仓库文件常用入口:

hbgithub_repo_edit.png

  • 1 branch :中文常叫「分支」。你可以理解为这个项目的不同版本。比如你用仓库存放你写的小说,构思了 N 个结局不确定哪个更好,就可以创建 N 各分支,写不同的版本,最后选择一个。如果是团队协作,请注意切换到你们正在共创的分支再编辑。
  • 2 create new file :在当前分支里新建文件。
  • 3 clone or download :把这个仓库内容同步到本地(来编辑)。

安人团队和开智课程里最常用的文件类型 MarkDown ,拓展名一般为 .md 。能在仓库里增、删、改这类文档,是你存活必备技能。最容易掌握的是在网页上操作,你可以通过下述图文指引快速上手。

在仓库中创建文件

  1. 切换到你要编辑的 branch(通常为 master branch),在仓库首页点击 create new file 按钮(按钮位置见上图标记 2 )。

  2. 填写文件名和正文内容:

    hbgithub_create_new_file2.png

    注意:在 code 中新建文件,文件名一定写上后缀,比如 MarkDown 文档请 加上 .md 要不渲染不正常无法正常显示哦。在 wiki 中的文件名则不需加后缀

  3. 修改好后,在「commit changes」的编辑框里注明所做改动。如果不知道怎么写比较好,可见 commit message 用语规范

  4. 点击 Commit changes 按钮,提交你的改动:

修改文件

  1. 点击文件名进入文件展示页面
  2. 点击文本框右上角的铅笔按钮,即可进入编辑模式
  3. 后续步骤同上述 3、4 步

创建文件夹

如果想在网页创建文件夹,只需在新建文件的界面,在 title 输入框里,输入你想创建的文件夹名称后加/即可:

hbgithub_create_folder.gif

网页基础操作就这些啦~

不过你迟早发觉,虽然网页操作最易掌握,但真的很不方便:1)编辑界面很不友好,远不如本地 MarkDown 编辑器好用。 2)操作风险大,一不小心没保存成功,又得重来……

还是本地大法好!如何把仓库里的文件同步到本地来编辑?且看 第二级:感觉良好,愈觉优雅 | 安人集团简明 GitHub 练级攻略

查看修改记录、添加评注

文件托管到 GitHub 后,你便可以方便地查看历史版本,对比版本差异:

code 模块

如果想查看仓库 code 里某文件的修改记录,可以在 web 找到该文件后,点击文本框右上角的对应按钮,查看改动记录:

hbgithub_file_history.png

在 history 页面进入具体版本即可给修改内容添加评注。具体操作见:如何给 code 文件改动添加评注

wiki 模块

wiki 模块的文档,也能查看修改记录,而且可以对比任意两个版本的修改记录哦。具体操作如下:

  1. 进入你想查看修改记录的文档,点击文档标题下的 revisions 链接:

    hbgithub_wiki_revision.png

  2. 进入该文档的历史页面,比如 https://github.com/OpenMindClub/Share/wiki/IdxCooperateBasicSkill/_history 。点击最右列的版本号(下图标记 A),即可查看该版本内容。在最左侧的勾选框(下图标记 B)勾选你想对比的两个版本,点击右上角的 compare revisions 按钮(下图标记 C),即可查看这俩版本的差异。

    hbgithub_wiki_history_compare.png

美中不足的是,查看 wiki 里的文件的版本差异时,无法添加评注……所以,某个文件到底放 code 还是 wiki ,除了根据团队惯用规则,还可以根据你自己的需求和这俩模块的特性差异判断哦。

整个仓库

如果你不止想看单个文件的改动记录,还想看整个仓库的修改记录,那点击仓库首页的 commits 就好啦。不过请先切换到你想查看的 branch 哦:

hbgithub_code_commit_link.png

能快速找到要用的仓库

除了点击别人给你的地址,如何快速进入自己要用的仓库?

登录 GitHub 后,点击导航栏最左边的 GitHub logo 、进入 dashboard 页面,就可以通过标有你名字的按钮快速切换 organization ,然后在页面右侧仓库列表进入你想找的仓库啦。

hbgithub_account-context-switcher-selected-dotcom.png

能快速找到要用的文件(web 版检索)

那如何快速找到 GitHub 仓库内容?

GitHub 内容可在云端查找,也可以在本地查找。至少知晓如何在网页上查阅文件,也是存活必备技能:

找某个仓库里的文件

进入仓库页面后,比如你现在在的这个页面,你会发现顶部导航栏有个搜索框「search」,直接在里头输入关键词,就能搜索你想查找的内容啦。还可以通过左侧菜单栏切换你想定位的类别。

hbgithub_search_repo.png

找某个 org 下的文件

如果不知道自己想搜索的内容在哪个仓库,还可以直接在整个 org 下搜索:

  • 方案一:进入这个 org 的主页,比如 https://github.com/OpenMindClub/ 直接在顶部导航栏搜索框中即可搜索
  • 方案二:随便一个 GitHub 页面,点击导航栏最左边的 GitHub logo 进入 dashboard 页面,切换为你想搜索的 organization ,即可搜索该 org 下相关内容。

验证自己已能存活

攻略看了那么多,是时候来做个小任务检验一下自己能否存活啦:

  1. 请 fork OpenMindClub/tacofancy 仓库到个人账号下生成自己的个人仓库 A (如果提示无法 fork 到个人账号下,通常是因为你已经 fork 过了)
  2. 在 A 仓库里新建一个文档 TEST.md ,在里头写下这句话:今天是(日期),我很(心情描述)
  3. 保存
  4. 把上述文档中的 日期 换成 星期几
  5. 保存

如果你有兴趣增加难度,可以试试把 TEST.md 放到你名字的文件夹下。

Bingo!

可以进军下一级别,体验更畅快的感觉啦!

FAQ

以下常见问题欢迎按需取用:

打开 GitHub 页面是 404 怎么办?

A:

安人集团团队仓库、开智课程所用仓库是私有库,访问需要权限。

如果你打开某个 GitHub 链接,显示 404 ,可能有两种情况:

  1. 你没登录自己的 GitHub 账号
  2. 你没成功加入相应的 Team

如果是第一种情况,登陆你的 GitHub 账号就成,比如在微信中点开 GitHub 链接显示 404 ,一般都是因为没登录。

如果在网络良好的环境下、登录 GitHub 账号后依然是 404,请把你的 GitHub Username 发给管理员:

  • 如果你是开智课程学员,请发邮件到 crm@openmindclub.com ,说明「我是 XX 课程学员, GitHub 主页地址是_____ 。登录 GitHub 后无法正常访问 XX 仓库,请核查我的权限。」
  • 如果你是安人团队成员,请联系团队 HR ,说明「我打不开 XXX 这个仓库地址,我的 GitHub 主页地址是_____ 。」

如果连 404 都不能显示,很可能是网络问题哦。请换个稳定的网络环境再尝试访问 GitHub 地址。

如何解决版本冲突(fix conflict)?

A:

多人编辑,难免出现 conflict 。好在 fix conflict 并不复杂,你熟悉 conflict 的标记,遇到时就不会满头包啦。

GitHub 会以 Conflict 标记告诉你,哪些是云端的版本,哪些是本地的版本。你删除标记后,合并云端和本地内容为最终想要的版本,便能正常同步到云端

<<<<<<<   HEAD

在这俩标记之间的通常是本地版本

=======

在这俩标记之间的通常是云端版本

>>>>>>> 版本号

如果还是不太明白,可以看看 Merge • GitHub & Git Foundations - YouTube。 # 需科学上网

如何回退到自己想要的版本?

A:

详见 Reverting a commit

如果你想无痕回退,可以用这个方式强制滚回某个版本

如何在 GitHub 上进行主题交流?

A:

前文已说,你可以把 GitHub 当成一个主题讨论平台。如何实现?用 GitHub issue 就好啦——你可以在 GitHub issues 发起议题,或参与已有议题。

在 GitHub issues 参与讨论时,你如果认同某条 comment ,可以点击该 comment 右上角的表情按钮,回应 大拇指/笑脸/礼花/爱心。

如果你想回复某条 comment 展开讨论,可以用 MarkDown 格式引用你想讨论的句子,空一行后回复。

例如:

GitHub issue 相较常见 BBS、论坛最大的区别是它可以 Close 和 Reopen 。

如果你发起的议题已经讨论完毕,请及时回复(comment)最新进展/解决方案到这个 issue 下并 Close issue,有始有终,让大伙儿知道这个议题已完成;同时保持主界面清爽。

如何优雅使用 GitHub issues?

A:

无论你用 issue 来做什么,都别忘了这个几个 issue 使用规则:

1. 一个 issue 只讨论一个问题

一个 issue 发布多个问题,比如 title 为「2w 课程疑问」的 issue 下有五六个当周疑问,相较一个 issue 只讨论一个问题,你觉得哪个 issue 更便于展开讨论、追踪和后期归档?

2. issue title 力求简短准确地描述问题

例如「写作实践中遇到的一些问题」 VS 「如何利用积累的卡片写出一篇文章?」 ,你更倾向点开哪个 issue 参与讨论?

3. issue 发布后不可删除,只能修改 title、正文或 close

issue 发布 issue 后,正文依然可编辑,且没有改动记录;所以如果你 comment 后要修订内容,只需点击 comment 右上角的编辑按钮(铅笔图标)。Issue title 也可编辑,但每一次改动都会有记录。

如何快速找到自己想看的 Issues ?

A:

如果某个仓库使用人员较多,仓库内出现大量 Issues 是正常的。

如何快速找到自己想看的 Issues ?多人协同神器 GitHub 提供了优雅的解决方案:

1. 全文检索

如下图所示,你可以在 Issues 的搜索框,检索 Issues 全文内容:

2. 自定义筛选

如下图所示,你还可以根据不同维度,筛选你想看的 Issues :

甚至:

啊哈,现在就去试试吧! GitHub Issues ,从此想看哪个就看哪个~

GitHub 有很多隐藏的进阶玩法,建议你在页面多多点击查看哟。

如何让别人快速查看 GitHub 页面某处内容?

A:

GitHub 用多了,你可能会有这样的困扰:

  • 有些 issue 很长,想让别人只看其中一个 comment ,有什么快捷方式吗? 直接复制 comment 文字内容或截图发给对方当然 OK ,但如果对方想回应这个 comment 呢?
  • 有些 GitHub 页面内容很多很长,想让别人快速查看某个部分的内容,有什么办法吗?

GitHub 都有优雅的解决方案——GitHub 页面隐含了非常多锚点,你一点击,便能快速定位一些内容。啥意思?你点击一下这个问题的标题,然后观察一下地址栏 URL 的变化?没错,点击一下就可以获取快速跳到这个标题位置的链接啦!这类可以快速定位页面内内容的标记就是**「锚点」**。

Issue 同理,你点击一下 issue comment 的时间(比如下图 A 的位置),会发现该页面地址末尾出现了 「#issuecomment-balabala」 ,再把此时的网页地址发给对方就可以啦:

邮箱被 GitHub 消息炸了咋办?

A:

刚用 GitHub 不久,你可能就被 GitHub 动态提醒邮件炸得心神不宁,但又不想错过精彩主题交流、笔记提交&互评、活动报名等重要通知。咋整?

作为汇聚全球顶尖 Hacker 的平台,GitHub 必然有优雅的解决方案。

推荐参加开智课程或在安人团队工作的的你选择这个方案:

  • 邮件接收 GitHub 通知,但仅收到自己参与的 Issues 消息和提到(@mention)自己的
  • 以邮件会话方式收到,而非每个 Issue comment 都为单独的一封邮件
  • 收到 GitHub 某仓库邮件能汇总到某个地方,空闲时可集中查阅处理,不会挤爆收件箱干扰正常工作

配置方式参见 HbGitHubNotifyStu · OpenMindClub/Share Wiki ,建议在 PC 端查看及配置。

BTW,遇到问题先找官方文档查阅一手资料是很多高手的默认习惯。入手一个新工具,先翻官方文档,而非查阅第三方教程,可以让自己少走很多弯路。

如何了解同伴们在 GitHub 上的动态?

A:

这么多同伴都在 GitHub 上输出创造,如何能及时了解他们的动态?

看完上一个问题的解决方案,细心如你肯定已经想到——如果他们输出在 GitHub repository(仓库),进入对应的 repository 点击 watching 就好了嘛!

如果你只想关注几个特定同伴的动态,这么做当然 OK ,但如果你想了解所上课程、所在团队所有同伴动态,这样 watching 多累啊~

强大的 GitHub 提供了更简单的方式——查看 dashboard 里的 News Feed - User Documentation

点击 GitHub 页面左上角的 GitHub 图标(上图箭头 1 位置),切换到仓库所在 organization (上图箭头 2&3),就可以看到相应同伴们的动态啦。

如果想查看和自己相关的 Issues ,进入 dashboard > Issues 即可:

这里还能分类查看 我创建的、指派给我的、提到我的 Issues :

经常查看「提到自己的 Issues」,就不易错过开智的重要消息啦。

CHANGELOG

  • 180227 闪闪增补查看版本对比的建议
  • 180225 闪闪根据内测反馈修订
  • 180424 闪闪增补完图片和链接
  • 180418 闪闪创建
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.