diff --git a/.gitignore b/.gitignore deleted file mode 100644 index bf3f68f..0000000 --- a/.gitignore +++ /dev/null @@ -1 +0,0 @@ -_version.inc diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index c3b7121..0000000 --- a/.gitmodules +++ /dev/null @@ -1,3 +0,0 @@ -[submodule "graphics"] - path = graphics - url = git://github.com/gotgit/gotgithub-graphics.git diff --git a/01-explore-github/010-what-is-github.rst b/01-explore-github/010-what-is-github.rst index 396c171..96e5ea3 100644 --- a/01-explore-github/010-what-is-github.rst +++ b/01-explore-github/010-what-is-github.rst @@ -1,90 +1,43 @@ -.. _what-is-github: +什么是GitHub +================ -============== - 什么是GitHub -============== -GitHub(网址 https://github.com/\ )是一个面向开源及私有软件项目的托管平台,\ -因为只支持Git作为唯一的版本库格式进行托管,故名GitHub。 +GitHub,网址 https://github.com/ ,是一个开源软件项目的托管平台,因为只使用Git作为唯一的版本库格式进行版本库托管,故名GitHub。GitHub的注册用户已经接近百万,托管的版本库数量已超两百万,其中不乏知名的开源项目,如:Ruby on Rails [#]_ ,Hibernate [#]_ ,phpBB [#]_ ,jQuery [#]_ ,Prototype [#]_ ,Homebrew [#]_ 等。 - -GitHub的注册用户已经超过百万\ [#]_\ ,托管的版本库数量已超三百万,其中不乏知\ -名的开源项目,如:Ruby on Rails\ [#]_\ 、Hibernate\ [#]_\ 、phpBB\ [#]_\ 、\ -jQuery\ [#]_\ 、Prototype\ [#]_\ 、Homebrew\ [#]_\ 等。 - -GitHub于2008年4月10日正式发布\ [#]_\ ,相比始于1999年的SourceForge\ [#]_\ 和\ -2005年的GoogleCode\ [#]_\ ,GitHub后来者居上。以2011年的数据从代码提交数量上\ -看,GitHub已经超越其前辈\ [#]_\ ,如图1-1所示。 +GitHub于2008年4月10日正式发布 [#]_ ,相比于始于1999年的SourceForge [#]_ 和2005年的GoogleCode [#]_ ,GitHub后来者居上,从代码提交数量上看,GitHub已经超越其前辈 [#]_ ,如图1-1所示。 .. figure:: /images/explore-github/survival-of-the-forges.png :scale: 100 图1-1:开源项目托管平台提交数量对照 -对于一个开源项目,从开发角度讲大体上分为两类人群,一类称为核心开发团队,他们\ -可以向保存源代码的版本库提交,即对源代码的修改具有最终的决定权。另外一类称为\ -贡献者,他们不属于核心开发团队,虽然也能看到源代码,但无权向版本库提交修改。 - -.. _cvcs-model: +对于一个开源项目,从开发角度讲大体上分为两类人群,一类称为核心开发团队,他们可以向保存源代码的版本库提交,即对源代码的修改具有最终的决定权。另外一类称为贡献者,他们不是核心团队的成员,虽然也能看到源代码,但是只可读不可写。 -采用传统的集中式版本控制系统(如SVN)的开源项目,这两个群体的用户体验都不是\ -太好。如图1-2所示,项目的贡献者(非核心成员)很不“高兴”,因为他们即便有修改\ -源代码的能力和渴望,也不能直接向版本库提交,要想成为提交者需要一个很长的建立\ -信任的过程。然而即便是核心开发团队的成员,体验也不是太好,因为凡是涉及到版本\ -库的操作(检入、检出、查看日志等)都需要在联网的状态下进行,网络带宽对用户\ -体验影响相当大。 +采用传统的集中式版本控制系统(如SVN)的开源项目,这两个群体的用户体验都不是太好。如图1-2所示,项目的贡献者(非核心成员)很不“高兴”,因为他们即便有修改代码的能力和渴望,也不能直接向版本库提交,要想成为提交者需要一个很长的建立信任的过程。对于项目的核心开发团队,体验也不是很好,因为凡是涉及到版本库的操作(检入、检出、查看日志等)都需要在联网的状态下运行,网络带宽对用户体验影响相当大。 -.. figure:: /images/explore-github/cvcs-model.png +.. figure:: /images/explore-github/svn-workflow.png :scale: 100 图1-2:使用集中式版本控制系统 -.. _dvcs-model: +Git等分布式版本控制系统的出现,彻底颠覆了原有代码管理的管理模式和组织架构。使用Git,不再需要唯一的、集中式的版本库,而是每个开发者本地都拥有一份完整的版本库克隆。Git并不排斥集中式的使用模式,但更倾向于将集中式模式下的版本库称为共享版本库,核心开发团队的成员可以将自己本地版本库的提交推送到共享版本库上。 -Git等分布式版本控制系统的出现,彻底颠覆了原有代码管理的组织模式。使用Git,\ -不再依赖唯一的、集中式的版本库,而是每个开发者本地都拥有一份完整的版本库。\ -Git并不排斥集中式的使用模式,但更倾向于将集中式版本库称为共享版本库。核心\ -开发团队的成员和贡献者(非核心成员)都可以从共享版本库克隆一份本地版本库,\ -但只有核心团队成员才可以将自己本地版本库的提交推送到共享版本库上。\ -如图1-3所示。 +使用Git做版本控制,如图1-3所示,核心开发团队非常“高兴”,因为他们和共享版本库之间不必一直保持连接状态,诸如查看日志、提交、创建分支等几乎全部操作都(脱离网络)在本地的版本库中完成。项目贡献者(非核心成员)也不再那么沮丧,因为版本库人人皆可更改(当然是对本地版本库而言)。稍微让贡献者感到困难的就是如何将自己的改动被核心开发团队所了解并接纳。Git提供了多种途径,一个方法是先用 ``git-format-patch`` 命令将本地提交转换为补丁文件或补丁文件序列,再通过邮件发送给核心开发团队。另外一个办法就是搭建一个自己专有的共享版本库,让核心团队的开发者到自己共享的版本库来抓取(Pull)。自己动手搭建Git服务器建立共享版本库是一个难点,在我的 +《Git权威指南》一书中花了七个章节来介绍,掌握起来有一定难度。 -.. figure:: /images/explore-github/dvcs-model.png +.. figure:: /images/explore-github/git-workflow.png :scale: 100 图1-3:使用分布式版本控制系统 -使用Git做版本控制(如图1-3所示),核心开发团队非常“高兴”,因为他们和共享\ -版本库之间不必一直保持连接状态,诸如查看日志、提交、创建分支等几乎全部操作\ -都(脱离网络)在本地的版本库中完成。项目贡献者(非核心成员)也不再那么沮丧,\ -因为版本库人人皆可更改(当然是对本地版本库而言)。稍微让贡献者感到困难的就是\ -如何将自己对项目的改进被核心开发团队所了解并接纳。Git提供了多种途径,一个方法\ -是先用\ ``git format-patch``\ 命令将本地提交转换为补丁文件或补丁文件序列,再\ -通过邮件发送给核心开发团队。另外一个办法就是搭建一个自己专有的共享版本库,\ -通过邮件创建一个拉拽请求(Pull Request),让核心团队的开发者到自己的版本库来\ -抓取(Pull)。 +GitHub的出现极大地改善了开源项目的生态环境,无论项目的核心开发团队,还是普通的项目贡献者都工作得非常“愉快”。项目的创建者只需在GitHub上点击一下鼠标即可创建一个新版本库。普通的项目贡献者在GitHub上先找到自己希望参与的项目,然后只需点击一下鼠标即可在自己的托管空间下创建一个派生的版本库(即项目分支),就好像这个项目原本就是由自己创立的那样。如图1-4所示,当普通的项目贡献者完成开发,可以通过GitHub的Web界面向项目的核心开发团队发送一个拖拽请求(Pull Request),项目的核心团队收到 Pull Request 后审核代码,审核通过后可以直接点击Web界面上的合并按钮完成对贡献者代码的合并。 -.. _github-model: - -GitHub的出现进一步推动了Git的普及,简化了版本控制的管理和操作流程,为开发者\ -提供了更好的交流平台。如图1-4所示。 - -.. figure:: /images/explore-github/github-model.png +.. figure:: /images/explore-github/github-workflow.png :scale: 100 图1-4:GitHub的协同模式 -使用GitHub,无论是项目的核心开发团队,还是普通的项目贡献者都工作得非常“愉快”。\ -创建项目变得非常轻松,创建者只需在GitHub上点击一下鼠标即可创建一个新版本库,\ -通过简单的Web操作即可完成项目授权进而组建项目核心团队。在GitHub中,\ -非核心团队成员参与项目也很容易。先找到自己希望参与的项目,然后只需在Web\ -上点击一下鼠标即可在自己的托管空间下创建一个派生(fork)的项目,\ -并对派生项目的版本库具有读写的完全权限,就好像这个项目原本就是由自己创立的\ -那样。当贡献者完成开发并向自己派生的版本库推送后,可以通过GitHub的Web界面向\ -项目的核心开发团队发送一个Pull Request,请求审核。项目的核心团队收到\ -Pull Request后审核代码,审核通过后可以直接通过Web界面执行合并操作接纳贡献者的提交。 - ---- -.. [#] https://github.com/blog/936-one-million .. [#] https://github.com/rails/rails .. [#] https://github.com/hibernate .. [#] https://github.com/phpbb/phpbb3 diff --git a/01-explore-github/020-github-hightlights.rst b/01-explore-github/020-github-hightlights.rst index d56391f..6a87a17 100644 --- a/01-explore-github/020-github-hightlights.rst +++ b/01-explore-github/020-github-hightlights.rst @@ -1,5 +1,3 @@ -.. _github-hightlights: - GitHub亮点 =============== @@ -7,55 +5,34 @@ GitHub亮点 1. 只用Git。 - GitHub只支持Git格式的版本库托管,而不像其他开源项目托管平台还对CVS、SVN、\ - Hg等格式的版本库进行托管。GitHub的哲学很简单,既然Git是最好的版本控制系统\ - 之一(对于很多喜欢Git和GitHub的人没有之一),没有必要为兼顾其他版本控制\ - 系统而牺牲Git某些独有特性。因此没有支持其他版本控制系统的历史负担,\ - 是GitHub成功的要素之一。 + GitHub只支持Git格式的版本库托管,而不像其他开源项目托管平台还对CVS、SVN、Hg等格式的版本库进行托管。GitHub的哲学很简单,既然Git是最好的版本控制系统之一(对于喜欢GitHub的人没有之一),没有必要为兼顾其他版本控制系统而牺牲Git某些独有特性。因此没有支持其他版本控制系统的历史负担,是GitHub成功的要素之一。 - 只用Git并不是说GitHub完全无视其他版本控制系统的使用者,相反,GitHub面向\ - SVN(Subversion)用户和Hg(Mercurial)用户开发了接口,让这些用户可以使用\ - SVN或Hg的客户端工具访问Git版本库。 + 只用Git并不是说GitHub完全无视其他版本控制系统的使用者,相反,GitHub面向SVN(Subversion)用户和Hg(Mercurial)用户开发了接口,让这些用户可以使用SVN或Hg的客户端工具访问Git版本库。 2. 对Git的完整支持。 - 相比其他开源项目托管平台,GitHub对Git版本库提供了完整的协议支持,支持HTTP\ - 智能协议、Git-daemon、SSH协议。相比只支持HTTP协议的GoogleCode,GitHub\ - 通过SSH协议可以实现版本库访问的无口令认证\ [#]_\ 。 + 相比其他开源项目托管平台,GitHub对Git版本库提供了完整的协议支持,支持HTTP智能协议、Git-daemon、SSH协议。相比只支持HTTP协议的GoogleCode,GitHub通过SSH协议可以实现版本库访问的无口令认证。 3. 无处不在的Git。 - 除了在版本库托管上使用Git,Git还被GitHub应用到更多领域。维基使用Git,\ - 可以通过克隆维基所在的版本库,离线修改维基;在线粘贴数据的Gist网站\ [#]_\ - 使用Git,记录变更历史;以及在Jekyll应用的帮助下,用Git版本库维护个人网站\ - 和博客等。 + 除了在版本库托管上使用Git,Git还被应用到GitHub更多的领域。维基使用Git,可以通过克隆维基所在的版本库,线下修改维基。在线粘贴信息的Gist网站 [#]_ 使用Git,记录变更历史。在Jekyll应用的帮助下,可以用Git版本库维护个人网站和博客。 4. 在线编辑文件。 - GitHub提供了在线编辑文件的功能,不熟悉Git的用户也可以直接通过浏览器修改\ - 版本库里的文件。 + GitHub提供了在线编辑文件的功能,即使不熟悉Git的用户也可以直接修改版本库里的文件。 5. 社交编程。 - 将社交网络引入项目托管平台是GitHub的创举。用户可以关注项目、关注其他用户\ - 进而了解项目和开发者动态。项目的派生(Fork)和拉拽请求(Pull Request)\ - 构成GitHub最独具一格的工作模式。对提交代码的逐行评注及Pull Request构成了\ - GitHub特色的代码审核。 + 将社交网络引入项目托管平台是GitHub的创举。用户可以关注项目、关注其他用户进而了解项目和开发者动态。项目的派生(Fork)和拉拽请求(Pull Request)构成GitHub最独具一格的工作模式。对提交代码的逐行评注及Pull Request构成了GitHub特色的代码审核。 6. 商业上的成功。 - GitHub通过私有版本库托管、面向企业的版本库托管和项目管理平台、人员招聘等\ - 付费服务获得了商业上的成功,这种成功使得GitHub不必以页面中嵌入广告的方式\ - 维持运营,最大的受益者还是用户。 + GitHub通过私有版本库托管、面向企业的版本库托管、人员招聘等付费服务获得了商业上的成功,这种成功使得GitHub不必以页面中嵌入广告的方式维持运营,最大的受益者还是用户。 7. 关注细节。 - GitHub网站采用了Ruby on Rails架构,在Web设计中运用了大量的JavaScript、\ - AJAX、HTML5等技术,支持对使用Markdown等标记语言的内容进行渲染和显示等。\ - 关注细节使得GitHub成为了项目托管领域的后起之秀。 + GitHub网站采用了Ruby on Rails的架构,在Web设计中运用了大量的JavaScript、AJAX、HTML5等技术,支持使用了Markdown等标记语言的文件自动渲染和显示,等等。关注细节使得GitHub成为了项目托管领域的后起之秀。 ---- -.. [#] 实际上使用HTTP协议也可以免口令输入。即通过文件\ ``~/.netrc``\ 写入\ - HTTP认证的明文口令。具体文件格式参见\ ``ftp``\ 命令MAN手册中相关介绍。 .. [#] https://gist.github.com/ diff --git a/01-explore-github/030-explore-github.rst b/01-explore-github/030-explore-github.rst index 832bdf9..c2e2b21 100644 --- a/01-explore-github/030-explore-github.rst +++ b/01-explore-github/030-explore-github.rst @@ -1,11 +1,7 @@ -.. _explore-github: - 探索GitHub =============== -打开浏览器,访问网址 https://github.com/\ ,来探索GitHub吧。GitHub的首页\ -(图1-5所示)特意给出了Git和GitHub的音标,可能不少国人需要据此校准一下\ -Git的读音\ [#]_\ 。 +打开浏览器,访问网址 https://github.com/ 来探索GitHub吧。GitHub的首页(图1-5所示)特意给出了Git和GitHub的音标,可能不少国人需要据此校准一下Git的读音 [#]_ 。 .. figure:: /images/explore-github/github-homepage.png :scale: 100 @@ -13,29 +9,24 @@ Git的读音\ [#]_\ 。 图1-5:GitHub的首页 -在首页的右上角是导航条,从左至右分别是:注册和收费方案、探索GitHub、功能、\ -博客和登录。还醒目地显示出不断增长着的注册用户数和托管的版本库数目。 +在首页的右上角是导航条,从左至右分别是:收费方案和注册、探索GitHub、功能、博客和登录。还醒目地显示出不断增长着的注册用户数和托管的版本库数目。 -如果想要了解GitHub上哪些项目最热门,进而寻找到好的开源产品,那么可以从导航条\ -中的“Explore GitHub”开始。图1-6显示通过对社交数据的分析得到的托管版本库动态趋势。 +如果想要了解GitHub上哪些项目最热门,进而寻找到好的开源产品,那么可以从导航条中的“Explore GitHub”开始。图1-6显示通过对社交数据的分析得到的托管版本库动态趋势。 .. figure:: /images/explore-github/explore-trends.png :scale: 100 图1-6:版本库动态趋势 -还可以根据感兴趣的人数、建立分支的数量、关注程度等寻找热门项目。图1-7显示\ -分支最多的项目是Homebrew —— 一款用ruby开发的苹果Mac OS X通用的非官方包管理\ -软件。考虑到不断攀升的苹果用户数量以及易于上手的ruby语言,这并不奇怪。 +还可以根据感兴趣的人数、建立分支的数量、关注程度等寻找热门项目。图1-7显示分支最多的项目是Homebrew —— 一款用ruby开发的苹果Mac OS X通用的非官方包管理软件。考虑到不断攀升的苹果用户数量以及易于上手的ruby语言,这并不奇怪。 .. figure:: /images/explore-github/explore-repositories.png :scale: 100 图1-7:热门版本库排行 -图1-8显示了托管版本库所用编程语言的动态分布,程序员多掌握几个热门编程语言\ -一定会对找工作有帮助。;-) +图1-8显示了托管版本库所用编程语言的动态分布,多掌握几个热门编程语言一定会对找工作有帮助。;-) .. figure:: /images/explore-github/explore-languages.png :scale: 100 @@ -43,34 +34,24 @@ Git的读音\ [#]_\ 。 图1-8:托管项目的编程语言统计 -GitHub通过屏幕截图等方式介绍了GitHub的常见功能,可以通过点击导航条中的\ -“Features”访问到。如图1-9可以看到在项目管理中,如何利用GitHub提供的团队管理\ -功能、维基、缺陷追踪以及代码审核。 +GitHub通过屏幕截图等方式介绍了GitHub的常见功能,可以通过点击导航条中的“Features”访问到。如图1-9可以看到在项目管理中,如何利用GitHub提供的团队管理功能、维基、缺陷追踪以及代码审核。 .. figure:: /images/explore-github/features-pm.png :scale: 100 图1-9:GitHub功能介绍 -.. _blog: - -博客也是了解GitHub的一个重要的途径,可以获知GitHub的最新动态,如最新改进等。\ -图1-10显示的是GitHub在感恩节推出的促销活动:收费服务免费试用一个月!\ [#]_\ -如果及时关注博客就不会错过噢。 - -.. _octocat: +博客也是了解GitHub的一个重要的途径,可以获知GitHub的最新动态,如最新改进等。图1-10显示的是GitHub在感恩节推出的促销活动:收费服务免费试用一个月!如果及时关注博客就不会错过噢。 .. figure:: /images/explore-github/blog.png :scale: 100 图1-10:GitHub博客 -图1-10的博客中一个由小章鱼和小猫组合而成的吉祥物,名字叫做Octocat。这个可爱的\ -GitHub吉祥物时不时会出来带给你惊喜。 +图1-10的博客中一个由小章鱼和小猫组合而成的吉祥物,名字叫做Octocat。这个可爱的GitHub吉祥物时不时会出来带给你惊喜。 马上到GitHub上注册,开始GitHub之旅。 ---- -.. [#] 《Git权威指南》第1页就提到了两种常见的对Git的读音错误。 -.. [#] http://git.io/N9WJ5w +.. [#] 《Git权威指南》第1页。 diff --git a/01-explore-github/index.rst b/01-explore-github/index.rst index be1f759..29d607a 100644 --- a/01-explore-github/index.rst +++ b/01-explore-github/index.rst @@ -1,9 +1,6 @@ -.. _github-overview: - 探索GitHub ******************** -熟悉Git\ [#]_\ 的人几乎都知道并喜欢GitHub\ [#]_\ ,反过来GitHub也吸引更多的\ -人来使用Git。GitHub正在成为开源项目托管的主要平台,是什么成就了GitHub? +熟悉Git [#]_ 的人几乎都知道并喜欢GitHub [#]_ ,反过来GitHub也吸引更多的人来使用Git。GitHub正在成为开源项目托管的主要平台,是什么成就了GitHub? .. toctree:: :maxdepth: 1 @@ -14,9 +11,9 @@ .. seealso:: - 本书并非一本介绍Git的书,并且假设读者已经掌握了Git的相关操作。如果读者对\ - Git尚不了解,可以参考我写的 《Git权威指南》\ [#]_\ 一书。此外还可以从网上\ - 找到很多免费的、很好的Git资料,如:Git社区书\ [#]_\ 、Pro Git\ [#]_\ 等。 + 本书并非一本介绍Git的书,并且假设读者已经掌握了Git的相关操作。 + 如果读者对Git尚不了解,可以参考我写的《Git权威指南》一书 [#]_ 。此外还可以从网上找到很多免费的、很好的Git资料, + 如:Git社区书 [#]_ 、Progit [#]_ 等。 ---- diff --git a/02-join-github/010-account-setup.rst b/02-join-github/010-account-setup.rst index d82f7b9..5d57068 100644 --- a/02-join-github/010-account-setup.rst +++ b/02-join-github/010-account-setup.rst @@ -1,141 +1,85 @@ -.. _github-signup: - 创建GitHub账号 =============== -注册GitHub账号,只要点击导航条中的“Signup and Pricing”,或者点击首页中那个\ -大大的“Plans, Pricing and Signup”按钮,即进入收费方案介绍及注册页面。 +注册GitHub账号,只要点击导航条中的“Pricing and Signup”,或者点击首页中那个大大的“Plans,Pricing and Signup”按钮,即进入收费方案介绍及注册页面。 -收费?不必担心,开源软件托管是GitHub的基石,对于开源项目的版本库(即非私有\ -版本库)的托管,GitHub是免费的。在收费方案及注册页面中,最上面的就是针对于\ -开源的免费托管方案,如图2-1所示。 +收费?不必担心,开源软件托管是GitHub的基石,对于开源项目的版本库(即非私有版本库)的托管,GitHub是免费的。在收费方案及注册页面中,最上面的就是针对于开源的免费托管方案,如图2-1所示。 .. figure:: /images/join-github/free-plan.png :scale: 100 图2-1:针对开源项目(公开版本库)的免费方案 -至于本页其他付费方案,将在后面的章节介绍。点击免费方案右侧的\ -“Create a free account”按钮,就进入到注册页面,如图2-2所示。 +至于本页其他付费方案,将在后面的章节介绍。点击免费方案右侧的“Create a free account”按钮,就进入到注册页面,如图2-2所示。 .. figure:: /images/join-github/signup.png :scale: 100 图2-2:账号注册 -GitHub的注册页面非常简洁,只有登录ID,邮件地址和口令需要输入。要注意的是\ -每个邮件地址只能注册一次。 - -注册完毕即以新注册的账号自动登录。登录后即进入用户的仪表板(Dashborad)\ -页面。首次进入的仪表板页面还会在其中显示GitHub BootCamp(GitHub 新手训练营)\ -的链接,以帮助新用户快速入门。如果图2-3所示。 +GitHub的注册页面非常简洁,只有登录ID,邮件地址和口令需要输入。要注意的是每个邮件地址只能注册一次。注册完毕即以新注册的账号自动登录,图2-3是以新注册的gotgithub用户登录后的首页。在首页右上方的导航条,可以看到当前登录用户的名称,如图2-3中显示为gotgithub。在登录用户名称前显示用户照片,因为尚未设置所以显示为缺省图片——GitHub吉祥物Octocat的剪影。点击导航条中的“Account Settings”,对账号进行进一步设置。 .. figure:: /images/join-github/loggedin.png :scale: 100 图2-3:登录后的GitHub首页 -仪表板页面是用户最重要的页面,因为创建新项目(新版本库)的链接就位于该页面。\ -重新设计的GitHub用户界面\ [#]_\ 中跳转到仪表板页面的链接不像之前那么直观,\ -鼠标移动到页面左上角的“github”文字图标会发现此图标可以点击,该文字图标即是\ -进入仪表板页面的快捷。 +图2-4对用户公开身份信息进行设置,所有内容均为可选项,如果填写将显示在个人页面中,并能被所有人访问。注意修改用户头像需要访问第三方头像设置网站:gravatar.com。Gravatar网站提供的头像服务是一个通用服务,可为大部分Web应用所使用。 -在页面右上方显示当前登录用户的名称和头像。图2-3中显示登录用户为 gotgithub,\ -而用户头像因为尚未设置所以显示为缺省图片——GitHub吉祥物Octocat的剪影。在页面\ -右上方还有三个图标,从左至右分别是:通知、账号设置和退出。点击账号设置图标\ -对账号进行进一步设置,如图2-4所示。 +图2-4中还显示了当前用户使用的GitHub托管方案(Free)和使用统计。因为当前注册用户选择的是免费方案,所以可用的私有版本库数量和私有空间协同者数目都是零。免费方案拥有300MB托管空间,因当前尚未创建版本库托管,所以空间占用为零。GitHub对开源软件的300MB托管空间限制并非硬性限制,可以申请扩增托管空间,如果不存在滥用情况的话。 .. figure:: /images/join-github/setting-profile.png :scale: 100 图2-4:账户设置页 -账号设置的第一个页面是对用户公开身份信息进行设置,所有内容均为可选项,如果\ -填写将显示在个人页面中,并能被所有人访问。注意修改用户头像需要访问第三方\ -头像设置网站:\ `gravatar.com`_\ ,Gravatar网站提供的头像服务是一个通用服务,\ -可为大部分Web应用所使用。 - -图2-4中还显示了当前用户使用的GitHub托管方案(Free)和使用统计。因为当前注册\ -用户选择的是免费方案,所以可用的私有版本库数量和私有空间的协同者数目都是零。\ -免费方案拥有300MB托管空间,因当前尚未创建版本库托管,所以空间占用为零。\ -GitHub对开源软件的300MB托管空间限制并非硬性限制,可以申请扩增托管空间,如果\ -不存在滥用情况的话。 - -点击菜单中的“Account Admin”,可以更改口令、查看API Token、修改用户名,以及\ -删除自身账号,如图2-5所示。 +点击菜单中的“Account Admin”,可以更改口令、查看API Token、修改用户名,以及删除自身账号,如图2-5所示。 .. figure:: /images/join-github/setting-admin.png :scale: 100 图2-5:账户管理 -.. _api-token: +其中API Token是和用户口令相关的密钥,当用户口令更改时API Token也随之更改。GitHub的某些应用会使用API Token进行身份认证,从而避免直接使用用户口令造成泄露的风险。API Token若泄露的危害要远远小于口令泄露,这因为API Token不能用于登录GitHub网站等,而且一旦API Token泄露可以很容易通过更改口令的方式更换API Token。 -其中API Token是和用户口令相关的密钥,当用户口令更改时API Token也随之更改。\ -GitHub的某些应用会使用API Token进行身份认证,从而避免直接使用用户口令造成\ -泄露的风险。API Token若泄露的危害要远远小于口令泄露,这因为API Token不能用于\ -登录GitHub网站等,而且一旦API Token泄露可以很容易通过更改口令的方式更换\ -API Token。 - -点击菜单中的“Email Addresses”,可以添加和删除邮件地址,如图2-6所示。GitHub\ -允许为一个账号绑定多个邮件地址,以便能够将Git版本库中的提交\ -(提交者以 "用户名 <邮件地址>" 的格式给出)正确对应到GitHub账户。 +点击菜单中的“Email Addresses”,可以添加和删除邮件地址,如图2-6所示。GitHub允许为一个账号绑定多个邮件地址,以便能够将Git版本库中的提交(提交者以 "用户名 <邮件地址>" 的格式给出)正确对应到GitHub账户。 .. figure:: /images/join-github/setting-email.png :scale: 100 图2-6:邮件地址管理 -.. _ssh: - -GitHub为托管的Git版本库提供SSH协议支持,即用户可以用公钥认证的方式连接到\ -GitHub的SSH服务器。下面的示例用ssh命令连接github.com的SSH服务,登录用户名为\ -git(所有GitHub用户共享此SSH用户名,不要写成其他)。 +GitHub为托管的Git版本库提供SSH协议支持,即用户可以以公钥认证的方式连接到GitHub的SSH服务器。下面的示例用ssh命令连接github.com的SSH服务,登录用户名为git(所有GitHub用户共享此SSH用户名,不要写成其他)。 :: $ ssh -T git@github.com Permission denied (publickey). -上面的示例显示登录失败,这是因为我们尚未在GitHub账户中正确设置公钥认证。\ -图2-7显示的是GitHub的SSH公钥设置界面。 +上面的示例显示登录失败,这是因为我们尚未在GitHub账户中正确设置公钥认证。图2-7显示的是GitHub的SSH公钥设置界面。 .. figure:: /images/join-github/setting-ssh.png :scale: 100 图2-7:SSH公钥管理 -要想向GitHub添加SSH公钥,首先要确保正确生成了对应的公钥/私钥对。关于SSH公钥\ -认证,在我的《Git权威指南》一书的“第29章使用SSH协议”中有详细介绍,这里仅做\ -简要的介绍。 +要想向GitHub添加SSH公钥,首先要确保正确生成了对应的公钥/私钥对。关于SSH公钥认证,在我的《Git权威指南》一书的“第29章使用SSH协议”中有详细介绍,这里仅做简要的介绍。 -GitHub的SSH服务支持OpenSSH格式的公钥认证,可以通过Linux、Mac OS X、或Cygwin\ -下的\ ``ssh-keygen``\ 命令创建公钥/私钥对。命令如下: +GitHub的SSH服务支持OpenSSH格式的公钥认证,可以通过Linux、Mac OS X、或Cygwin下的 ``ssh-keygen`` 命令创建公钥/私钥对。命令如下: :: $ ssh-keygen -然后根据提示在用户主目录下的\ ``.ssh``\ 目录中创建默认的公钥/私钥对文件,\ -其中\ ``~/.ssh/id_rsa``\ 是私钥文件,\ ``~/.ssh/id_rsa.pub``\ 是公钥文件。\ -注意私钥文件要严加保护,不能泄露给任何人。如果在执行\ ``ssh-keygen``\ 命令时\ -选择了使用口令保护私钥,私钥文件是经过加密的。至于公钥文件\ -``~/.ssh/id_rsa.pub``\ 则可以放心地公开给他人。 +然后根据提示在用户主目录下的 .ssh 目录中创建默认的公钥/私钥对文件,其中 ``~/.ssh/id_rsa`` 是私钥文件, ``~/.ssh/id_rsa.pub`` 是公钥文件。注意私钥文件要严加保护,不能泄露给任何人,如果在执行 ``ssh-keygen`` 命令时选择了使用口令保护私钥,私钥文件是经过加密的。公钥文件 ``~/.ssh/id_rsa.pub`` 则可以放心地公开给任何人。 -也可以用\ ``ssh-keygen``\ 命令以不同的名称创建多个公钥,当拥有多个GitHub\ -账号时,非常重要。这是因为虽然一个GitHub账号允许使用多个不同的SSH公钥,\ -但反过来,一个SSH公钥只能对应于一个GitHub账号。下面的命令在\ ``~/.ssh``\ 目录\ -下创建名为\ ``gotgithub``\ 的私钥和名为\ ``gotgithub.pub``\ 的公钥文件。 +也可以用 ``ssh-keygen`` 命令以不同的名称创建多个公钥,当拥有多个GitHub账号时,非常重要。这是因为虽然一个GitHub账号允许使用多个不同的SSH公钥,但反过来,一个SSH公钥只能对应于一个GitHub账号。下面的命令在 ``~/.ssh`` 目录下创建名为 ``gotgithub`` 的私钥和名为 ``gotgithub.pub`` 的公钥文件。 :: $ ssh-keygen -C "gotgithub@gmail.com" -f ~/.ssh/gotgithub -当生成的公钥/私钥对不在缺省位置(\ ``~/.ssh/id_rsa``\ 等)时,使用\ ``ssh``\ 命令\ -连接远程主机时需要使用参数\ ``-i ``\ 指定公钥/私钥对。或者在配置\ -文件\ ``~/.ssh/config``\ 中针对相应主机进行设定。例如对于上例创建了非缺省\ -公钥/私钥对\ ``~/.ssh/gotgithub``\ ,可以在\ ``~/.ssh/config``\ 配置文件中\ -写入如下配置。 +当生成的公钥/私钥对不在缺省位置(~/.ssh/id_rsa等)时,可以在 ``ssh`` 命令中用 ``-i `` 指定,或者在配置文件 ``~/.ssh/config`` 中通过相应的设置进行设定。例如对于上例创建了非缺省公钥/私钥对 ``~/.ssh/gotgithub`` ,可以在 ``~/.ssh/config`` 配置文件中写入如下配置。 :: @@ -145,35 +89,23 @@ GitHub的SSH服务支持OpenSSH格式的公钥认证,可以通过Linux、Mac O PreferredAuthentications publickey IdentityFile ~/.ssh/gotgithub -好了,有了上面的准备,就将\ :file:`~/.ssh/gotgithub.pub`\ 文件内容拷贝到剪切板。\ -公钥是一行长长的字符串,若用编辑器打开公钥文件会折行显示,注意拷贝时切莫在其中\ -插入多余的换行符、空格等,否则在公钥认证过程因为服务器端和客户端公钥不匹配而\ -导致认证失败。命令行下可直接用\ ``pbcopy``\ 命令\ [#]_\ 将文件内容拷贝到剪切板\ -以避免拷贝错误: - -:: - - $ cat ~/.ssh/gotgithub.pub | pbcopy +.. 通过在配置文件 ``~/.ssh/config`` 中添加不同的 Host 主机名,可以实现在同一个客户端用Git命令(以SSH协议)访问不同的GitHub账户。 - -然后将公钥文件中的内容粘贴到GitHub的SSH公钥管理的对话框中,如图2-8所示。\ +好了,有了上面的准备,就可以把公钥文件中的内容复制到GitHub的SSH公钥管理的对话框中。注意整个公钥为一行,不要断行。 .. figure:: /images/join-github/setting-ssh-gotgithub.png :scale: 100 图2-8:添加SSH公钥认证 -设置成功后,再用\ ``ssh``\ 命令访问GitHub,会显示一条认证成功信息并退出。\ -在认证成功的信息中还会显示该公钥对应的用户名。 +设置成功后,再用 ``ssh`` 命令访问 github.com,会显示一条认证成功信息,然后退出。在认证成功的信息中还会显示该公钥对应的用户名。 :: $ ssh -T git@github.com Hi gotgithub! You've successfully authenticated, but GitHub does not provide shell access. -如果您未能看到类似的成功信息,可以通过在\ ``ssh``\ 命令后面添加\ ``-v``\ 参数\ -加以诊断,会在冗长的会话中看到认证所使用的公钥文件等信息。然后比对所使用的公钥\ -内容是否和GitHub账号中设置的相一致。 +如果您未能看到类似的成功信息,可以通过在 ``ssh`` 命令后面添加 ``-v`` 参数加以诊断,会在冗长的会话中看到认证所使用的公钥文件等信息。 :: @@ -187,25 +119,10 @@ GitHub的SSH服务支持OpenSSH格式的公钥认证,可以通过Linux、Mac O Hi gotgithub! You've successfully authenticated, but GitHub does not provide shell access. ... -账号设置的最后一项是向GitHub提供你的求职信息。GitHub作为一个优秀程序员的聚集地,\ -已成为一个IT人才招聘的途径,如果你需要找工作的话,提供简历并打开“Available for hire”\ -选项,GitHub会向你推荐合适的工作机会。如图2-9所示。 +账号设置的最后一项是向GitHub提供你的求职信息。GitHub作为一个优秀程序员的聚集地,已经成为重要的IT人才招聘途径,如果你需要找工作的话,提供简历并打开“Available for hire”选项,如图2-9所示。 .. figure:: /images/join-github/setting-job.png :scale: 100 图2-9:求职信息管理 -.. _gravatar.com: http://gravatar.com/ - ----- - -.. [#] https://github.com/blog/1007-skinny-header -.. [#] Mac下的命令行工具\ ``pbcopy``\ 和\ ``pbpaste``\ 可以在命令行下操作剪贴板,\ - Linux下的命令行工具\ ``xsel``\ 亦可实现类似功能。在Linux下可以创建别名用\ - ``xsel``\ 命令来模拟\ ``pbcopy``\ 和\ ``pbpaste`` \。 - - :: - - alias pbcopy='xsel --input' - alias pbpaste='xsel --output' diff --git a/02-join-github/020-browse-repo.rst b/02-join-github/020-browse-repo.rst index dec3ec7..cb71948 100644 --- a/02-join-github/020-browse-repo.rst +++ b/02-join-github/020-browse-repo.rst @@ -1,29 +1,18 @@ -.. _browse-repo: - 浏览托管项目 =============== -在上一节学习了如何建立GitHub的账户,接下来在建立自己的项目托管之前,\ -先来看看别人是怎么做的。 - -在GitHub中搜索字符串“GotGit”,可以搜索到我建立的一个项目,项目地址是:\ -https://github.com/gotgit/gotgit/\ 。\ -由上至下,GotGit项目首页可以分为如下几个区域。 +GitHub的账户已经建立好了,在建立自己的项目托管之前,看看别人是怎么做的。在GitHub中搜索字符串“GotGit”,可以搜索到我建立的一个项目,项目地址是: https://github.com/gotgit/gotgit/ 。由上至下,GotGit项目首页可以分为四个区域。 * 区域一:项目概要介绍及版本库URL等。 - 项目GotGit托管在组织账号 gotgit 之下\ [#]_\ ,并且已经有若干关注用户和派生\ - 项目。最下面一行显示版本库的访问地址,只显示了HTTP和Git-daemon两个协议的\ - URL地址,这是因为当前用户对该版本库只具有只读权限,因此没有显示SSH协议的URL\ - 地址。 + 项目GotGit托管在组织账号 gotgit 之下 [#]_ ,并且当前有4个关注用户和2个项目分支。最下面一行显示版本库的访问地址,只显示了HTTP和Git-daemon两个协议的URL地址,这是因为当前用户对该版本库只具有只读权限,因此没有显示SSH协议的URL地址。 .. figure:: /images/join-github/gotgit-repo-tree-1.png :scale: 100 图2-10:版本库概要信息 - 使用任意一种协议均可克隆该Git版本库,但要注意只有Git 1.6.6及以上版本才支持\ - 智能HTTP协议,低版本Git则无法用HTTP协议克隆GitHub上的版本库\ [#]_\ 。 + 使用任意一种协议均可克隆该Git版本库,但要注意只有Git 1.6.6及以上版本才支持智能HTTP协议,低版本Git则无法用HTTP协议克隆GitHub上的版本库 [#]_ 。 :: @@ -35,157 +24,125 @@ https://github.com/gotgit/gotgit/\ 。\ $ git clone git://github.com/gotgit/gotgit.git -* 区域二:代码浏览子菜单及分支切换对话框。 - 默认项目代码页(即项目首页)显示项目文件列表(即\ ``Files``\ 子菜单),如\ - 图2-11所示。右侧还显示项目\ ``gotgit/gotgit``\ 默认的分支为\ ``gh-pages``\ - 而非常见的\ ``master``\ 分支。关于\ ``gh-pages``\ 分支,在“第3.5.2节 :ref:`project-homepage`\ ”\ - 会介绍该分支的神奇用途。 - - .. figure:: /images/join-github/gotgit-repo-tree-1-submenu.png - :scale: 100 - - 图2-11:代码浏览子菜单及分支 - -* 区域三:显示最新提交的提交说明、提交用户头像、提交时间等提交信息。\ - 右侧还显示此次提交对应的提交ID。 +* 区域二:显示提交说明、提交用户头像、提交时间等提交信息。右侧还显示此次提交对应的提交ID、树ID,及父提交ID等。 .. figure:: /images/join-github/gotgit-repo-tree-2.png :scale: 100 - 图2-12:提交信息 + 图2-11:提交信息 -* 区域四:目录树。每个目录和文件后面还显示最后一次变更的提交说明。 +* 区域三:目录树。每个目录和文件后面还显示最后一次变更的提交说明。 .. figure:: /images/join-github/gotgit-repo-tree-3.png :scale: 100 - 图2-13:目录树 + 图2-12:目录树 -* 区域五:根目录下的文件\ ``README.md``\ 格式化为HTML输出。 +* 区域四:根目录下的文件 ``README.mkd`` 格式化为HTML输出显示。 - GitHub内置了多种文本标记语言的支持,如Markdown、Textile、reStructuredText、\ - asciidoc、Wiki等。当发现根目录下的\ ``README``\ 文件后,会根据其扩展名判断\ - 所用的标记语言类型,自动转换为HTML格式显示。 + GitHub内置了多种文本标记语言的支持,如Markdown、Textile、reStructuredText、asciidoc、Wiki等。当发现根目录下的 ``README`` 文件后,会根据其使用的标记语言类别,自动转换为HTML格式显示。 .. figure:: /images/join-github/gotgit-repo-tree-4.png :scale: 100 - 图2-14:README文件 + 图2-13:README文件 在GitHub的页面中可以使用键盘快捷键,按下问号(?)会在弹出窗口显示当前页面可用的快捷键。 -在项目的代码浏览页按下字母“w”,弹出分支切换菜单,如图2-15所示。 +在项目的首页可以按下字母"p",显示当前提交的父提交。图2-14就是当按下字母"p"后,切换到父提交(对照图2-11)。 -.. figure:: /images/join-github/gotgit-repo-switch-branch.png +.. figure:: /images/join-github/gotgit-repo-tree-parent.png :scale: 100 - 图2-15:快捷键“w”切换分支 + 图2-14:快捷键"p"切换到父提交 -按下字母“t”,开启目录树中文件查找和过滤。图2-16就是在按下字母“t”后,当逐一输入\ -单词“download”时的过滤效果。 +按下字母"f",开启目录树中文件查找和过滤。图2-15就是在按下字母"f"后,当逐一输入单词"download"时的过滤效果。 .. figure:: /images/join-github/gotgit-repo-tree-filter.png :scale: 100 - 图2-16:快捷键“t”开启过滤器在目录树中搜索 + 图2-15:快捷键t开启过滤器在目录树中搜索 -点击代码浏览子菜单中的“Commits”(提交)显示版本库GotGit的提交历史,如图2-17所示。 +点击菜单中的“Commits”(提交)显示版本库GotGit的提交历史,如图2-16所示。 .. figure:: /images/join-github/gotgit-repo-commit-history.png :scale: 100 - 图2-17:提交历史 + 图2-16:提交历史 -提交历史页面也支持快捷键,按下问号(?)或者点击页面中的键盘标志会显示快捷键\ -帮助。其中快捷键"j"和"k"用于在提交列表中向上和向下选择提交,在选中的提交按下\ -回车键,会显示该提交包含的文件改动差异,如图2-18所示。 +提交历史页面也支持快捷键,按下问号(?)或者点击页面中的键盘标志会显示快捷键帮助。其中快捷键"j"和"k"用于在提交列表中向上和向下选择提交,在选中的提交按下回车键,会显示该提交包含的文件改动差异,如图2-17所示。 .. figure:: /images/join-github/gotgit-repo-commit-diff.png :scale: 100 - 图2-18:文本文件改动差异 - -在文本文件的差异比较中,不但将有差异的行标识出来,还将行内具体改动的字词用\ -特殊颜色进行了标识,不由得感叹GitHub的细致入微。 + 图2-17:文本文件改动差异 -.. _image-diff: +在文本文件的差异比较中,不但将有差异的行标识出来,还将行内具体改动的字词用特殊颜色进行了标识,不由得感叹GitHub的细致入微。 -GitHub还支持对图形文件的差异比较,并提供四种比较方式。在如下地址:\ -http://git.io/image-diff\ [#]_\ 提供了一个示例提交。您可以去尝试一下不同的图形\ -文件比较方式,以便更直观地观察图形文件前后的改动。 +GitHub还支持对图形文件的差异比较,并提供四种比较方式。在如下地址: http://goo.gl/Gy85b [#]_ 提供了一个示例提交,尝试一下使用不同的图形文件比较方式,查看该提交对图形文件的改动。 -* 默认修改前后的两幅图片左右并排显示,如图2-19所示。 +* 默认修改前后的两幅图片左右并排显示,如图2-18所示。 .. figure:: /images/join-github/image-diff-2-up.png :scale: 100 - 图2-19:左右并排比较图形文件差异 + 图2-18:左右并排比较图形文件差异 -* 选择交换显示比较修改前后的图片,用鼠标左右拖动进度条,可以非常直观地看到\ - 图片的差异。如图2-20所示。 +* 选择交换显示比较修改前后的图片,用鼠标左右拖动进度条,可以非常直观地看到图片的差异。如图2-19所示。 .. figure:: /images/join-github/image-diff-swipe.png :scale: 100 - 图2-20:交换显示图形文件比较差异 + 图2-19:交换显示图形文件比较差异 * 还提供洋葱皮和色差比较,自己动手试试吧。 -网络图是GitHub的一大特色,显示一个项目的版本库被不同用户派生(Fork)后,\ -各个版本库的派生关系。这个网络图最早使用Flash实现的,目前已经改为HTML5\ -实现\ [#]_\ 。图2-21的示例网络图来自于Gitosis项目\ [#]_\ 。 +网络图是GitHub的一大特色,显示一个项目的版本库被不同用户派生(Fork)后,各个版本库的派生关系。这个网络图最早使用Flash实现的,目前已经改为HTML5实现 [#]_ 。图2-20的示例网络图来自于Gitosis项目。 .. figure:: /images/join-github/network-graph.png :scale: 100 - 图2-21:Gitosis项目网络图 + 图2-20:Gitosis项目网络图 -Pull Requests(拉拽请求)是派生(Fork)版本库的开发者向项目贡献提交的方法。\ -如图2-22所示,GotGit项目目前没有未被处理的Pull Request,但是可以看到有一个\ -已经关闭的Pull Request请求。 +Pull Requests(拉拽请求)是派生(Fork)版本库的开发者向项目贡献提交的方法。如图2-21所示,GotGit项目目前没有未被处理的Pull Request,但是可以看到有一个已经关闭的Pull Request请求。 .. figure:: /images/join-github/gotgit-repo-pull-request.png :scale: 100 - 图2-22:Pull Requests界面 + 图2-21:Pull Requests界面 -这个Pull Request是GitHub用户agate发现了GotGit脚本中一个和ruby1.9不兼容的Bug,\ -当我把agate派生版本库中的提交合并到GotGit版本库后,该Pull Request自动关闭。\ -整个Pull Request的变更记录如图2-23所示。 +这个Pull Request是GitHub用户agate发现了GotGit脚本中一个和ruby1.9不兼容的Bug,当我把agate派生版本库中的提交合并到GotGit版本库后,该Pull Request自动关闭。整个Pull Request的变更记录如图2-22所示。 .. figure:: /images/join-github/gotgit-repo-pull-request-detail.png :scale: 100 - 图2-23:Pull Request的变更历史 + 图2-22:Pull Request的变更历史 -缺陷追踪(Issue)也是GitHub工作流中一个重要的组件。GotGit项目用缺陷跟踪系统\ -帮助维护《Git权威指南》一书的勘误,图2-24可以看到当前有2个打开的问题和9个\ -已关闭的问题。 +缺陷追踪(Issue)也是GitHub工作流中一个重要的组件。GotGit项目用缺陷跟踪系统帮助维护《Git权威指南》一书的勘误,图2-23可以看到已关闭问题中有一个网友发现书的中的文字错误。 .. figure:: /images/join-github/gotgit-repo-issue.png :scale: 100 - 图2-24:缺陷追踪 + 图2-23:缺陷追踪 -GitHub还为项目提供报表分析。图2-25是GotGit项目中用到的开发语言分布图。 +GitHub还为项目提供图像化报表分析。图2-24是GotGit项目中用到的开发语言分布图。 .. figure:: /images/join-github/gotgit-repo-graph-lang.png :scale: 100 - 图2-25:GotGit项目开发语言分布图 + 图2-24:GotGit项目开发语言分布图 -图2-26是开发者对GotGit项目贡献分布图。 +图2-25是开发者对GotGit项目贡献分布图。 .. figure:: /images/join-github/gotgit-repo-graph-impact.png :scale: 100 - 图2-26:GotGit项目贡献分布图 + 图2-25:GotGit项目贡献分布图 ---- .. [#] 项目 gotgit 最早由用户 ossxp-com 创建,现已转移到组织 gotgit 账号之下。 .. [#] https://github.com/blog/809-git-dumb-http-transport-to-be-turned-off-in-90-days -.. [#] 短格式URL,实际对应于: https://github.com/cameronmcefee/Image-Diff-View-Modes/commit/8e95f7 +.. [#] 短格式URL,实际对应于: https://github.com/cameronmcefee/Image-Diff-View-Modes/commit/8e95f70c9c47168305970e91021072673d7cdad8 .. [#] https://github.com/blog/621-bye-bye-flash-network-graph-is-now-canvas -.. [#] https://github.com/res0nat0r/gitosis diff --git a/02-join-github/030-be-social.rst b/02-join-github/030-be-social.rst index bf7b4b5..457dbed 100644 --- a/02-join-github/030-be-social.rst +++ b/02-join-github/030-be-social.rst @@ -1,51 +1,40 @@ -.. _soc: - 社交网络 =============== -社交网络的一大特征就是用户间的相互关注,从而形成朋友圈或媒体圈,实现便捷的\ -信息分享和传播。GitHub支持项目级别及用户级别的关注。 +社交网络的一大特征就是用户间的相互关注,从而形成朋友圈或媒体圈,实现便捷的信息分享和传播。GitHub支持项目级别及用户级别的关注。 关注一个项目很简单,只需点击项目名称右侧的“Watch”按钮。 .. figure:: /images/join-github/watch-project.png :scale: 100 - 图2-27:项目的关注按钮 + 图2-26:项目的关注按钮 -添加对项目的关注后,点击页面左上角的“github”文字图标进入仪表板(Dashboard)\ -页面,如图2-28所示。 +添加对项目的关注后,在“Dashboard”(仪表板)页面的左侧会显示关注项目的最新动态,右侧会列表显示关注的项目。如图2-27所示。 .. figure:: /images/join-github/dashboard-with-watched-prj.png :scale: 100 - 图2-28:关注项目在仪表板页的显示 - -仪表板页面的左侧显示所关注项目的最新动态,右侧会列表显示关注的项目列表。 + 图2-27:关注项目在仪表板页的显示 -GitHub还可以关注用户。访问 https://github.com/mojombo 可以看到mojombo(GitHub\ -创始者之一)的用户页,关注他只需点击图2-29中的“Follow”按钮。从mojombo的用户页\ -还可以看到majombo关注的开发者,可以以此扩大GitHub朋友圈。 +GitHub还可以关注用户。访问 https://github.com/mojombo 可以看到mojombo(GitHub创始者之一)的用户页,关注他只需点击图2-28中的“Follow”按钮。从mojombo的用户页还可以看到majombo关注的开发者,可以以此扩大GitHub朋友圈。 .. figure:: /images/join-github/github-mojombo.png :scale: 100 - 图2-29:mojombo的用户页 + 图2-28:mojombo的用户页 -GitHub仪表板页面,有一个“RSS Feed”链接,如图2-30所示。点击该链接可以使用RSS客户端\ -(如Google Reader)订阅,实现无需登录GitHub即可访问所关注的项目和人的动态。 +GitHub仪表板页面,有一个“RSS Feed”链接,如图2-29所示。点击该链接可以使用RSS客户端(如Google Reader)订阅,实现无需登录GitHub即可访问所关注的项目和人的动态。 .. figure:: /images/join-github/rss-feed.png :scale: 100 - 图2-30:RSS Feed + 图2-29:RSS Feed -RSS中可能包括隐私信息,如私有版本库的更新信息,那么RSS订阅是如何保护个人隐私\ -呢?难道需要口令认证么?查看一下RSS订阅的URL,你会看到类似如下格式的URL地址: +RSS中可能包括隐私信息,如私有版本库的更新信息,那么RSS订阅是如何保护个人隐私呢?难道需要口令认证么?查看一下RSS订阅的URL,你会看到类似如下格式的URL地址: :: - https://github.com/gotgithub.private.atom?token=681a8a5a38419ecfb80f8633d4cb4e16 + https://github.com/gotgithub.private.atom?token=7fa3febca074046415a6308a3f673a4a -原来RSS订阅用到了API Token进行身份认证,即保障了个人RSS的私密性,又避免直接\ -使用明文口令导致的密码泄露。关于API Token,参见本章\ :ref:`第2.1节中相关介绍 `\ 。 +原来RSS订阅用到了API Token,既保护了隐私,又不怕密码泄露。关于API Token参见本章第一节的相关介绍。 diff --git a/02-join-github/index.rst b/02-join-github/index.rst index e874bfb..28108f7 100644 --- a/02-join-github/index.rst +++ b/02-join-github/index.rst @@ -1,8 +1,6 @@ -.. _join-github: - 加入GitHub ******************** -本章介绍如何在GitHub上注册账号,并以现有项目为例介绍GitHub的主要功能。 +本章介绍如何在GitHub上注册账号,并以一个已有项目为例介绍GitHub的主要功能。 .. toctree:: :maxdepth: 1 diff --git a/03-project-hosting/010-new-project.rst b/03-project-hosting/010-new-project.rst index 4dea1a4..dfd93d5 100644 --- a/03-project-hosting/010-new-project.rst +++ b/03-project-hosting/010-new-project.rst @@ -1,17 +1,10 @@ -.. _new-project: - 创建新项目 =============== -.. _new-repo: - 新版本库即是新项目 ---------------------- -在GitHub,一个项目对应唯一的Git版本库,创建一个新的版本库就是创建一个新的项目。\ -访问仪表板(Dashboard)页面,如图3-1,可以看到关注的版本库中已经有一个,\ -但自己的版本库为零。在显示为零的版本库列表面板中有一个按钮“New Repository”,\ -点击该按钮开始创建新版本库。 +在GitHub,一个项目对应唯一的Git版本库,创建一个新的版本库就是创建一个新的项目。访问仪表板(Dashboard)页面,如图3-1,可以看到关注的版本库中已经有一个,但自己的版本库为零。在显示为零的版本库列表面板中有一个按钮“New Repository”,点击该按钮。 .. figure:: /images/project-hosting/new-repo-btn.png :scale: 100 @@ -25,85 +18,73 @@ 图3-2:创建新项目 -我们为新建立的版本库命名为“helloworld”,\ -相应的项目名亦为“helloworld”,创建完毕后访问项目页,提示版本库\ -尚未初始化,并给出如何初始化版本库的帮助,如图3-3所示。 +GitHub中,每个项目都对应于唯一的Git版本库,所以创建项目即是创建版本库,反之亦然。我们创建的新项目名为“helloworld”,创建完毕后访问项目页,提示版本库尚未初始化,并给出如何初始化版本库的帮助,如图3-3所示。 .. figure:: /images/project-hosting/project-uninitial.png :scale: 100 图3-3:项目尚未初始化 -在图3-3中可以看到访问协议增加了一个支持读写的SSH协议,访问地址为:\ -``git@github.com:gotgithub/helloworld.git``\ 。注意任何GitHub用户均可使用该\ -URL访问此公开版本库,但只有版本库建立者gotgithub具有读写权限,其他人\ -只有只读权限。在初始化版本库之前,最好先确认是否是用正确的公钥进行认证,如下: +在图3-3中可以看到访问协议增加了一个支持读写的SSH协议,访问地址为: ``git@github.com:gotgithub/helloworld.git`` 。注意任何GitHub用户均可使用该URL访问此公开版本库,但只有版本库建立者 `gotgithub` 具有读写权限,其他人只有只读权限。在初始化版本库之前,最好先确认是否是用正确的公钥进行认证,如下: :: $ ssh -T git@github.com Hi gotgithub! You've successfully authenticated, but GitHub does not provide shell access. -.. _init-by-clone: - 版本库初始化 -------------- -如果是从头创建版本库,可以采用先克隆,建立提交数据,最后再通过推送完成GitHub\ -版本库的初始化。步骤如下: +如果是从头创建版本库,可以采用先克隆,建立提交数据,最后再通过推送完成GitHub版本库的初始化。步骤如下: -* 克隆版本库。 - - 克隆过程会显示警告,不过这个警告可以忽略,因为GitHub创建的版本库本来就是一个\ - 空白的版本库。 +* 克隆版本库。克隆过程会显示警告,可以尽管忽略该警告,因为GitHub创建的版本库本来就是一个空白的版本库。 :: $ git clone git@github.com:gotgithub/helloworld.git - Cloning into 'helloworld'... + Cloning into helloworld... warning: You appear to have cloned an empty repository. -* 创建文件\ ``README.md``\ [#]_\ 。 +* 创建文件 ``README.mkd`` [#]_ 。 - 下面是一段示例文字,把这段文字保存为文件\ ``README.md``\ ,该文件的内容将会\ - 直接显示在项目首页中(显示效果参见后面的图3-5)。 + 下面是一段示例文字,把这段文字保存为文件 ``README.mkd`` ,该文件的内容将会直接显示在项目首页中(显示效果参见后面的图3-5)。 :: - # 我的第一个GitHub项目 - - 这是项目 [helloworld](https://github.com/gotgithub/helloworld) , + # 我的第一个GitHub项目 # + + 这是项目**helloworld**, 欢迎访问。 - 这个项目的版本库是 **Git格式** ,在 Windows、Linux、Mac OS X - 平台都有客户端工具可以访问。虽然版本库只提供Git一种格式, - 但是你还是可以用其他用其他工具访问,如 ``svn`` 和 ``hg`` 。 + 这个项目的版本库是 *Git格式* ,在 Windows、Linux、 + Mac OS X 平台都可以访问。甚至你可以用 ``svn`` 和 ``hg`` + 命令来访问。 - ## 版本库地址 + ## 版本库地址 ## - 支持三种访问协议: + 支持三种访问协议: - * HTTP协议: `https://github.com/gotgithub/helloworld.git` 。 - * Git协议: `git://github.com/gotgithub/helloworld.git` 。 - * SSH协议: `ssh://git@github.com/gotgithub/helloworld.git` 。 + * [HTTP协议](https://github.com/gotgithub/helloworld.git)。 + * [Git协议](git://github.com/gotgithub/helloworld.git)。 + * [SSH协议][link3]。 - ## 克隆版本库 + ## 克隆版本库 ## 操作示例: $ git clone git://github.com/gotgithub/helloworld.git + + ---- + + [link3]: ssh://git@github.com/gotgithub/helloworld.git - 上面这段文字采用Markdown格式,您也可以使用其他支持的格式,只要确保\ ``README``\ - 文件使用正确的扩展名。本书附录部分介绍了Markdown及其他GitHub支持的标记语言。\ - 关于Markdown,目前我们只需知道这一个易于识别和理解的纯文本格式,可以方便的\ - 转换为HTML。Markdown语法非常像我们在写邮件(纯文本)时用空行来分隔段落、\ - 用星号开启列表、用缩进表示引用内容等等。 + 上面这段文字采用Markdown格式,您也可以使用其他支持的格式,只要确保 ``README`` 文件使用正确的扩展名。附录详细介绍了Markdown及其他GitHub支持的标记语言。关于Markdown,目前我们只需知道这一个易于识别和理解的纯文本格式,可以方便的转换为HTML。Markdown语法非常像我们在写邮件(纯文本)时用空行来分隔段落、用缩进表示内容引用等等。 -* 添加\ ``README.md``\ 文件并提交。 +* 添加 ``README.mkd`` 文件并提交。 :: - $ git add README.md + $ git add README.mkd $ git commit -m "README for this project." * 向GitHub推送,完成版本库初始化。 @@ -112,44 +93,37 @@ URL访问此公开版本库,但只有版本库建立者gotgithub具有读写 $ git push origin master -然后查看GitHub上新建项目的首页。项目首页的上半部分可见版本库包含了一个新的\ -提交,以及版本库目录树中包含的文件,如图3-4所示。 +然后查看GitHub上新建项目的首页。项目首页的上半部分可见版本库包含了一个新的提交,以及版本库目录树中包含的文件,如图3-4所示。 .. figure:: /images/project-hosting/project-pushed-head.png :scale: 100 图3-4:完成推送后的项目首页上半部分 -在项目首页的下半部分,会看到\ ``README.md``\ 文件被转换为HTML显示,如图3-5所示。 +在项目首页的下半部分,会看到 ``README.mkd`` 文件被转换为HTML显示,如图3-5所示。 .. figure:: /images/project-hosting/project-pushed-tail.png :scale: 100 图3-5:完成推送后的项目首页下半部分 -.. _init-by-push: - 从已有版本库创建 ----------------- -如果在GitHub项目初始化之前,数据已经存在于本地版本库中,显然像上面那样先克隆、\ -再提交、后推送的方法就不适宜了。应该采用下面的方法。 +在GitHub项目创建之前,如果版本库就已经存在,显然向上面的先克隆、再提交、后推送的方法就不适宜了。应该采用下面的方法。 -为试验新的版本库初始化方法,先把刚刚新建的测试项目“helloworld”删除,\ -同时也将本地工作区中克隆的“helloworld”删除。\ -警告:删除项目的操作非常危险,不可恢复,慎用。 +在试验新方法初始化版本库之前,先删除再重建 `helloworld` 项目。注意:删除项目操作非常危险,不可恢复,慎用。 -* 点击项目首页中项目名称旁边的“Admin”按钮进入项目管理页,再点击页面最下方的\ - 删除版本按钮,如图3-6所示。 +* 点击项目首页中项目名称旁边的“Admin”按钮进入项目管理页,再点击页面最下方的删除版本按钮,如图3-6所示。 .. figure:: /images/project-hosting/project-delete.png :scale: 100 图3-6:删除项目 -* 然后再重建版本库“helloworld”,如本章一开始图3-2所示。 +* 然后再重建项目,如本章一开始图3-2所示。 -接下来使用下面的步骤完成“helloworld”版本库的初始化。 +接下来使用下面的步骤完成 `helloworld` 版本库的初始化。 * 本地建立一个Git版本库。 @@ -159,21 +133,20 @@ URL访问此公开版本库,但只有版本库建立者gotgithub具有读写 $ cd helloworld $ git init -* 然后在版本库中添加示例文件,如\ ``README.md``\ 文件,内容同前。 +* 然后在版本库中添加示例文件,如 ``README.mkd`` 文件,内容同前。 :: - $ git add README.md + $ git add README.mkd $ git commit -m "README for this project." -* 为版本库添加名为\ ``origin``\ 的远程版本库。 +* 为版本库添加名为 ``origin`` 的远程版本库。 :: $ git remote add origin git@github.com:gotgithub/helloworld.git -* 执行推送命令,完成GitHub版本库的初始化。注意命令行中的\ ``-u``\ 参数,在推送\ - 成功后自动建立本地分支与远程版本库分支的追踪。 +* 执行推送命令,完成GitHub版本库的初始化。注意命令行中的 ``-u`` 参数,在推送成功后自动建立本地分支和远程分支的跟踪。 :: @@ -181,5 +154,4 @@ URL访问此公开版本库,但只有版本库建立者gotgithub具有读写 ---- -.. [#] 以扩展名\ ``.md``\ ,\ ``.mkd``\ ,\ ``.mkdn``\ ,\ ``.mdown``\ ,\ ``.markdown``\ - 等为结尾的文件,均以Markdown标记语言语法进行解析并显示。 +.. [#] 以扩展名 ``.md``, ``.mkd``, ``.markdown`` 结尾的文件均Markdown标识语言语法解析并显示。 diff --git a/03-project-hosting/020-repo-operation.rst b/03-project-hosting/020-repo-operation.rst index ce4cbf5..898962a 100644 --- a/03-project-hosting/020-repo-operation.rst +++ b/03-project-hosting/020-repo-operation.rst @@ -1,36 +1,27 @@ -.. _git-operations: - 操作版本库 =============== -.. _noff-push: - 强制推送 ---------- -细心的读者可能从图3-4已经看出,显示的提交者并非gotgithub用户,而是一个名为\ -ossxp-com的用户,这是因为GitHub是通过提交中的邮件地址来对应到GitHub用户的。\ -看看提交说明: +细心的读者可能从图3-4已经看出,显示的提交者并非gotgithub用户,而是一个名为ossxp-com的用户,这是因为GitHub是通过提交中的邮件地址来对应到GitHub用户的。看看提交说明: :: $ git log --pretty=fuller - commit 92dee9b8125afc9a606394ed463f9f264f2d3d58 + commit a00f4dda9f72d1f71eed6b6269dd7327951446f1 Author: Jiang Xin - AuthorDate: Wed Dec 14 14:52:40 2011 +0800 + AuthorDate: Thu Aug 11 16:31:39 2011 +0800 Commit: Jiang Xin - CommitDate: Wed Dec 14 14:52:40 2011 +0800 - + CommitDate: Thu Aug 11 16:31:39 2011 +0800 + README for this project. -原来提交用户设置的邮件地址并非gotgithub用户设置的邮件地址。补救办法就是对此\ -提交进行修改,然后强制推送到GitHub。 +原来提交用户设置的邮件地址并非gotgithub用户设置的邮件地址。补救办法就是对此提交进行修改,然后强制推送到GitHub。 -* 重新设置\ ``user.name``\ 和\ ``user.email``\ 配置变量。 +* 重新设置 ``user.name`` 和 ``user.email`` 配置变量。 - 因为gotgithub是一个仅在本书使用的示例账号,我可不想影响本地其他项目的提交,\ - 因此下面的设置命令没有使用\ ``--global``\ 参数,只对本地\ ``helloworld``\ - 版本库进行设置。 + 因为gotgithub是一个测试用的临时用户,我并不希望影响我在本地其他项目的提交,因此下面的设置命令没有使用 ``--global`` 参数,只对本地版本库进行设置。 :: @@ -39,9 +30,7 @@ ossxp-com的用户,这是因为GitHub是通过提交中的邮件地址来对 * 执行Git修补提交命令。 - 注意使用参数\ ``--reset-author``\ 会将提交信息中的属性\ ``Author``\ 连同\ - ``AuthorDate``\ 一并修改,否则只修改\ ``Commit``\ 和\ ``CommitDate``\ 。\ - 参数\ ``-C HEAD``\ 维持提交说明不变。 + 注意使用 ``--reset-author`` 会将提交信息中的属性 ``Author`` 连同 ``AuthorDate`` 一并修改,否则只修改 ``Commit`` 和 ``CommitDate`` 。参数 ``-C HEAD`` 维持提交说明不变。 :: @@ -52,19 +41,16 @@ ossxp-com的用户,这是因为GitHub是通过提交中的邮件地址来对 :: $ git log --pretty=fuller - commit e1e52d99fa71fd6f606903efa9da04fd0055fca9 + commit f172c51a111d558130028c7e9c3e81b60196d512 Author: Jiang Xin - AuthorDate: Wed Dec 14 15:05:47 2011 +0800 + AuthorDate: Thu Aug 11 18:23:56 2011 +0800 Commit: Jiang Xin - CommitDate: Wed Dec 14 15:05:47 2011 +0800 + CommitDate: Thu Aug 11 18:23:56 2011 +0800 README for this project. * 直接推送会报错。 - 错误信息中出现\ ``non-fast-forword``\ (非快进式推送),含义为要推送的提交并非\ - 继远程版本库最新提交之后的提交,推送会造成覆盖导致服务器端有数据(提交)会丢失。 - :: $ git push @@ -77,9 +63,7 @@ ossxp-com的用户,这是因为GitHub是通过提交中的邮件地址来对 * 使用强制推送。 - 对于此例,考虑到还没有其他人关注\ ``helloworld``\ 这个刚刚建立的示例项目,\ - 显然不需要向上面命令的错误信息所提示的那样先执行\ ``git pull``\ 合并上游版本库\ - 再推送,而是选择强制推送,以新的修补提交覆盖包含错误提交者ID的提交。 + 对于此例,我们显然不需要向上面命令错误信息中提示那样先执行 ``git pull`` 合并上游版本库再推送,而是选择强制推送。 :: @@ -87,55 +71,44 @@ ossxp-com的用户,这是因为GitHub是通过提交中的邮件地址来对 Counting objects: 3, done. Delta compression using up to 2 threads. Compressing objects: 100% (2/2), done. - Writing objects: 100% (3/3), 629 bytes, done. - Total 3 (delta 0), reused 0 (delta 0) + Writing objects: 100% (3/3), 597 bytes, done. + Total 3 (delta 0), reused 2 (delta 0) To git@github.com:gotgithub/helloworld.git - + 92dee9b...e1e52d9 master -> master (forced update) + + a00f4dd...f172c51 master -> master (forced update) -完成强制推送后,再查看GitHub项目页面,会发现提交者已经显示为gotgithub用户。\ -如图3-7所示。 +完成强制推送后,再查看GitHub项目页面,会发现提交者已经显示为gotgithub用户。如图3-7所示。 .. figure:: /images/project-hosting/force-push.png :scale: 100 图3-7:强制更新后,提交者已更改 -.. _new-branch: - 新建分支 --------- -Git的分支就是保存在\ ``.git/refs/heads/``\ 命名空间下的引用。引用文件的内容是\ -该分支对应的提交ID。当前版本库中的默认分支\ ``master``\ 就对应于文件\ -``.git/refs/heads/master``\ 。 - -若在GitHub版本库中创建分支,首先要在本地版本库中创建新的分支(即引用),\ -然后用推送命令将本地创建的新的引用连同所指向的提交推送到GitHub版本库中\ -完成GitHub上分支的创建。操作如下: +现在版本库中只有一个默认分支 ``master`` ,如果希望在GitHub版本库中再创建分支,可以采用如下方法: -* 本地版本库中建立新分支\ ``mybranch1``\ 。 +* 本地版本库中建立分支 ``mybranch1`` 。 - 创建分支有多种方法,如使用\ ``git branch``\ 命令,但最为便捷的就是\ - ``git checkout -b``\ 命令,同时完成新分支的创建和分支切换。 + 创建分支有多种方法,最为便捷的就是 ``git checkout -b`` 命令,同时完成分支创建和分支切换。 :: $ git checkout -b mybranch1 Switched to a new branch 'mybranch1' -* 为了易于识别,添加一个新文件\ ``hello1``\ ,并提交。 +* 为了易于识别,添加一个新文件 ``hello1`` ,并提交。 :: $ touch hello1 $ git add hello1 $ git commit -m "add hello1 for mark." - [mybranch1 f46a284] add hello1 for mark. + [mybranch1 73e586f] add hello1 for mark. 0 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 hello1 -* 通过推送命令,将本地分支\ ``mybranch1``\ 推送到GitHub远程版本库,完成在GitHub\ - 上的新分支创建。 +* 通过推送命令,将本地分支 ``mybranch1`` 推送到GitHub远程版本库,完成在GitHub上的新分支创建。 :: @@ -143,51 +116,44 @@ Git的分支就是保存在\ ``.git/refs/heads/``\ 命名空间下的引用。 Counting objects: 4, done. Delta compression using up to 2 threads. Compressing objects: 100% (2/2), done. - Writing objects: 100% (3/3), 281 bytes, done. + Writing objects: 100% (3/3), 280 bytes, done. Total 3 (delta 0), reused 0 (delta 0) To git@github.com:gotgithub/helloworld.git * [new branch] mybranch1 -> mybranch1 Branch mybranch1 set up to track remote branch mybranch1 from origin. -在GitHub上查看版本库,会看到新增了一个分支\ ``mybranch1``\ ,不过默认分支仍为\ -``master``\ ,如图3-8所示。 +在GitHub上查看版本库,会看到新增了一个分支 ``mybranch1`` ,不过默认分支仍为 ``master`` ,如图3-8所示。 .. figure:: /images/project-hosting/new-branch.png :scale: 100 图3-8:版本库新增了一个分支 -.. _default-branch: - 设置默认分支 --------------- -可以改变GitHub上版本库显示的默认分支,如果版本库包含多个分支的话。\ -例如修改版本库的默认分支为\ ``mybranch1``\ ,点击项目名称旁边的“Admin”按钮,\ -修改项目的默认分支。如图3-9所示。 +如果希望版本库的默认分支为 ``mybranch1`` ,点击项目名称旁边的”Admin“按钮,修改项目的默认分支,如图3-9所示。 .. figure:: /images/project-hosting/set-default-branch.png :scale: 100 图3-9:设置缺省分支 -设置了GitHub默认分支后,如果再从GitHub克隆版本库,本地克隆后版本库的默认分支\ -也将改变。 +设置了GitHub默认分支后,如果再从GitHub克隆版本库,本地克隆后版本库的默认分支也将改变。 :: $ git clone git@github.com:gotgithub/helloworld.git helloworld-nb - Cloning into 'helloworld-nb'... + Cloning into helloworld-nb... remote: Counting objects: 6, done. remote: Compressing objects: 100% (4/4), done. remote: Total 6 (delta 0), reused 6 (delta 0) - Receiving objects: 100% (6/6), done. + Receiving objects: 100% (6/6), 845 bytes, done. $ cd helloworld-nb $ git branch * mybranch1 -实际上修改GitHub上版本库的默认分支,就是将GitHub版本库的头指针\ ``HEAD``\ -指向了其他分支,如\ ``mybranch1``\ 分支。这可以从下面命令看出。 +之所以本地缺省分支不再是 ``master`` ,是因为远程(GitHub)版本库中的特殊引用 ``HEAD`` 指向 ``mybranch1`` 分支。这可以从下面命令看出。 :: @@ -196,37 +162,33 @@ Git的分支就是保存在\ ``.git/refs/heads/``\ 命名空间下的引用。 origin/master origin/mybranch1 -也可以从\ ``git ls-remote``\ 命令看出头指针\ ``HEAD``\ 和引用\ ``refs/heads/mybranch1``\ -指向同一个对象的哈希值。 +也可以从 ``git ls-remote`` 命令看出引用 ``HEAD`` 和 ``refs/heads/mybranch1`` 指向同一个对象的哈希值。 :: $ git ls-remote From git@github.com:gotgithub/helloworld.git - f46a28484adb6c1b4830eb4df582325c740e9d6c HEAD - e1e52d99fa71fd6f606903efa9da04fd0055fca9 refs/heads/master - f46a28484adb6c1b4830eb4df582325c740e9d6c refs/heads/mybranch1 - -.. _del-branch: + 73e586f46f5a4a476e415f248714e595ddbe2f7f HEAD + f172c51a111d558130028c7e9c3e81b60196d512 refs/heads/master + 73e586f46f5a4a476e415f248714e595ddbe2f7f refs/heads/mybranch1 删除分支 --------------- -删除当前工作分支会报错。例如下面的命令试图分支\ ``mybranch1``\ ,但没有成功: +删除本地版本库的分支 ``mybranch1`` ,用如下命令: :: $ git branch -d mybranch1 error: Cannot delete the branch 'mybranch1' which you are currently on. -错误信息显示不能删除当前工作分支。因此先切换到其他分支,例如从GitHub版本库\ -中取出\ ``master``\ 分支并切换。 +错误信息显示不能删除当前工作分支。因此先切换到其他分支,例如从GitHub版本库中取出 ``master`` 分支并切换。 :: - $ git checkout master + $ git checkout -b master origin/master -可以看出新的工作分支为\ ``master``\ 分支。 +可以看出新的工作分支为 ``master`` 分支。 :: @@ -234,19 +196,14 @@ Git的分支就是保存在\ ``.git/refs/heads/``\ 命名空间下的引用。 * master mybranch1 -现在可以删除\ ``mybanch1``\ 分支。下面的命令之所以使用\ ``-D``\ 参数,\ -而非\ ``-d``\ 参数,是因为Git在删除分支时为避免数据丢失,默认禁止删除\ -尚未合并的分支。参数\ ``-D``\ 则可强制删除尚未合并的分支。 +现在删除 ``mybanch1`` 分支。之所以使用 ``-D`` 参数,而非 ``-d`` 参数,是因为为了防止 ``mybranch1`` 的提交丢失,Git缺省禁止删除尚未合并的分支。 :: $ git branch -D mybranch1 - Deleted branch mybranch1 (was f46a284). + Deleted branch mybranch1 (was 73e586f). -现在只是本地分支被删除了,远程GitHub服务器上的\ ``mybranch1``\ 分支尚在。\ -删除远程GitHub版本库中的分支就不能使用\ ``git branch``\ 命令,而是要使用\ -``git push``\ 命令,不过在使用推送分支命令时要使用一个特殊的引用表达式\ -(冒号前为空)。如下: +现在只是本地分支被删除了,远程GitHub服务器上的 ``mybranch1`` 分支尚在。删除远程GitHub版本库中的分支就不能使用 ``git branch`` 命令而,而是要使用 ``git push`` 命令,不过在使用推送分支命令时要使用一个特殊的引用表达式(冒号前为空)。如下: :: @@ -258,10 +215,7 @@ Git的分支就是保存在\ ``.git/refs/heads/``\ 命名空间下的引用。 为什么删除远程分支出错了呢?是因为没有使用强制推送么? -实际上即使使用强制推送也会遇到上面的错误。GitHub发现要删除的\ ``mybranch1``\ -分支是远程版本库的缺省分支,因而禁止删除。重新访问GitHub的项目管理页面,\ -将缺省分支设置回\ ``master``\ 分支,参照图3-9。然后再次执行如下命令,即可成功\ -删除分支。 +实际上即使使用强制推送也会遇到上面的错误。GitHub发现要删除的 ``mybranch1`` 分支是版本库的缺省分支,因而禁止删除。重新访问GitHub的项目管理页面,将缺省分支设置回 ``master`` 分支,参照图3-9。然后再执行上述命令,即可成功删除分支。 :: @@ -269,34 +223,18 @@ Git的分支就是保存在\ ``.git/refs/heads/``\ 命名空间下的引用。 To git@github.com:gotgithub/helloworld.git - [deleted] mybranch1 -执行\ ``git ls-remote``\ 命令可以看到GitHub远程版本库已经不存在分支\ ``mybranch1``\ 。 +执行 ``git ls-remote`` 命令可以看到GitHub远程分支已删除。 :: $ git ls-remote git@github.com:gotgithub/helloworld.git - From git@github.com:gotgithub/helloworld.git - e1e52d99fa71fd6f606903efa9da04fd0055fca9 HEAD - e1e52d99fa71fd6f606903efa9da04fd0055fca9 refs/heads/master - -.. _git-tags: + f172c51a111d558130028c7e9c3e81b60196d512 HEAD + f172c51a111d558130028c7e9c3e81b60196d512 refs/heads/master 里程碑管理 ------------ -里程碑即tag,其管理和分支管理非常类似。里程碑和分支一样也是以引用的形式存在的,\ -保存在\ ``.git/refs/tags/``\ 路径下。引用可能指向一个提交,但也可能是其他类型(Tag对象)。 - -- 轻量级里程碑:用\ ``git tag []`` 命令创建,引用直接指向\ - 一个提交对象\ ````\ 。 - -- 带说明的里程碑:用\ ``git tag -a []`` 命令创建,并且在创建时\ - 需要提供创建里程碑的说明。Git会创建一个tag对象保存里程碑说明、里程碑的指向、\ - 创建里程碑的用户等信息,里程碑引用指向该Tag对象。 - -- 带签名的里程碑:用\ ``git tag -s []`` 命令创建。是在带说明的\ - 里程碑的基础上引入了PGP签名,保证了所创建的里程碑的完整性和不可拒绝性。 - -下面演示一下里程碑的创建和管理。 +里程碑管理和分支管理极其类似。 * 先在本地创建一个新提交。 @@ -306,7 +244,7 @@ Git的分支就是保存在\ ``.git/refs/heads/``\ 命名空间下的引用。 $ git add hello1 $ git commit -m "add hello1 for mark." -* 本地创建里程碑\ ``mytag1``\ 、\ ``mytag2``\ 和\ ``mytag3``\ 。 +* 本地创建里程碑 ``mytag1`` 、 ``mytag2`` 和 ``mytag3`` 。 :: @@ -331,9 +269,9 @@ Git的分支就是保存在\ ``.git/refs/heads/``\ 命名空间下的引用。 Counting objects: 6, done. Delta compression using up to 2 threads. Compressing objects: 100% (4/4), done. - Writing objects: 100% (5/5), 548 bytes, done. - Total 5 (delta 0), reused 0 (delta 0) - To git@github.com:gotgithub/helloworld.git + Writing objects: 100% (5/5), 564 bytes, done. + Total 5 (delta 0), reused 2 (delta 0) + To git@github.github.com:gotgithub/helloworld.git * [new tag] mytag1 -> mytag1 * [new tag] mytag2 -> mytag2 * [new tag] mytag3 -> mytag3 @@ -343,15 +281,15 @@ Git的分支就是保存在\ ``.git/refs/heads/``\ 命名空间下的引用。 :: $ git tag -d mytag3 - Deleted tag 'mytag3' (was c71231c) + Deleted tag 'mytag3' (was de60c49) * 删除GitHub远程版本库中的里程碑。 :: $ git push origin :mytag3 - To git@github.com:gotgithub/helloworld.git - [deleted] mytag3 + To git@github.github.com:gotgithub/helloworld.git + - [deleted] mytag3 此时查看GitHub上的项目页,会看到已有两个里程碑,如图3-10所示。 @@ -359,3 +297,5 @@ Git的分支就是保存在\ ``.git/refs/heads/``\ 命名空间下的引用。 :scale: 100 图3-10:里程碑列表 + + diff --git a/03-project-hosting/030-repo-authz.rst b/03-project-hosting/030-repo-authz.rst index 5570e09..519f4d7 100644 --- a/03-project-hosting/030-repo-authz.rst +++ b/03-project-hosting/030-repo-authz.rst @@ -1,69 +1,32 @@ -.. _pubkey-mgmt: - 公钥认证管理 ================ -开发者向GitHub版本库写入最常用到的协议是SSH协议,因为SSH协议使用公钥认证,\ -可以实现无口令访问,而若使用HTTPS协议每次身份认证时都需要提供口令\ [#]_\ 。\ -使用SSH公钥认证,就涉及到公钥的管理。 - -.. _pubkeys: +开发者向GitHub版本库写入最常用的是SSH协议,因为SSH协议使用公钥认证,可以实现无口令访问,而若使用HTTPS协议每次身份认证时都需要提供口令。使用SSH公钥认证,就涉及到公钥的管理。 用户级公钥管理 --------------- -开发者可能会从不止一台电脑访问GitHub中的版本库(用SSH协议),因不同的电脑有\ -不同的公钥/私钥对,这就需要为GitHub账号添加多个公钥。点击账号设置中的\ -“SSH Public Keys”进入SSH公钥管理界面,如图3-11所示。 +开发者可能会从不止一台电脑访问GitHub中的版本库(用SSH协议),因不同的电脑有不同的公钥/私钥对,这就需要为GitHub账号添加多个公钥。点击账号设置中的“SSH Public Keys”进入SSH公钥管理界面,如图3-11所示。 .. figure:: /images/project-hosting/ssh-public-keys.png :scale: 100 图3-11:SSH多公钥管理 -如图3-11,在创建gotgithub账号一开始,就手工添加了名为“My Mac OS X”的公钥,\ -显然这是为苹果电脑准备的。图中正在添加的名为“Key on Windows”是为Windows环境\ -下使用SSH协议访问GitHub准备的公钥。 - -当添加了新的公钥后,无论是从哪台电脑(苹果或PC)用SSH协议访问版本库时都拥有\ -相同授权,即都是以gotgithub账号身份来访问。例如用户级公钥访问GitHub的SSH服务,\ -在提示信息中会显示用户ID,如下: - -:: - - $ ssh -T git@github.com - Hi gotgithub! You've successfully authenticated, but GitHub does not provide shell access. +如图3-11,在创建gotgithub账号一开始,就添加了名为“My Mac OS X”的公钥,显然这是为苹果电脑准备的。图中正在添加的名为“Key on Windows”是为Windows环境下使用SSH协议访问GitHub准备的公钥。 -.. _deploy-keys: +当添加了新的公钥后,无论是从哪台电脑(苹果或PC)用SSH协议访问版本库时都拥有相同授权,即都是以gotgithub账号身份来访问。 项目级公钥管理 ------------------ -多增加一个用户级别的公钥,就意味着可以从另外一台电脑访问该用户所有版本库。\ -但有时只希望从某台电脑上向某一个版本库“写入”,其他版本库则不可写,这可以通过\ -设置版本库级别的公钥认证实现。 +多增加一个用户级别的公钥,就意味着可以从另外一台电脑访问该用户所有版本库。但有时只希望从某台电脑上向某一个版本库“写入”,其他版本库则不可写,这可以通过设置版本库级别的公钥认证实现。 -以项目管理者(创建者)身份登录GitHub,例如以gotgithub用户身份访问\ -``gotgithub/helloworld``\ 版本库,进入到项目的管理页面,选择菜单中的\ -“Deploy Keys”,即可设置项目级别公钥。如图3-12所示。 +以项目管理者(创建者)身份登录GitHub,例如以gotgithub用户身份访问 ``gotgithub/helloworld`` 版本库,进入到项目的管理页面,选择菜单中的“Deploy Keys”,即可设置项目级别公钥。如图3-12所示。 .. figure:: /images/project-hosting/deploy-keys.png :scale: 100 图3-12:项目级公钥管理 -就像一个用户可以设置多个用户级公钥一样,也可以为一个项目设置多个项目级公钥。\ -无论是项目级公钥还是用户级公钥都有同样的限制:一个公钥只能使用一次。 - -当使用项目级公钥访问GitHub的SSH服务,会在提示信息中显示版本库ID而非用户ID。\ -如下的命令输出中显示了版本库ID\ ``gotgithub/helloworld``\ 。 - -:: - - $ ssh -i ~/.ssh/deploy-key -T git@github.com - Hi gotgithub/helloworld! You've successfully authenticated, but GitHub does not provide shell access. - ----- -.. [#] 可以通过在文件\ ``~/.netrc``\ 中写入明文口令实现使用 HTTPS 协议时也能\ - 自动完成认证。具体格式参见\ ``ftp``\ 命令的MAN手册中相关介绍。 diff --git a/03-project-hosting/040-repo-hooks.rst b/03-project-hosting/040-repo-hooks.rst index 2b7e290..1ba2605 100644 --- a/03-project-hosting/040-repo-hooks.rst +++ b/03-project-hosting/040-repo-hooks.rst @@ -1,25 +1,14 @@ -.. _hooks: - 版本库钩子扩展 ================== -通过钩子扩展,GitHub托管的版本库可以和外部应用实现整合。整合的接口完全开放,\ -开发者可以访问GitHub的开源项目 `github/github-services`_ 开发新的应用整合脚本。\ -目前GitHub已经支持超过50个外部应用的整合,在这里恕不一一列举,仅以\ -``helloworld``\ 项目为例,介绍几个常见应用的整合。 +通过钩子扩展,GitHub托管的版本库可以和外部应用实现整合。整合的接口完全开放,开发者可以访问GitHub的开源项目 `github/github-services`_ 开发新的应用整合。目前GitHub已经支持超过50个外部应用的整合,在这里恕不一一列举,仅以 ``helloworld`` 项目为例,介绍几个常见应用的整合。 .. _github/github-services: https://github.com/github/github-services -.. _mail-notify-hook: - 邮件通知功能 -------------- -配置邮件通知,可以实现新提交推送至版本库时,发送通知邮件。在版本库的管理界面,\ -选择“Service Hooks”中的Email进入邮件通知配置界面,如图3-15所示。配置界面很简单,\ -写上邮件地址,选择激活即可。为了便于整个团队都能收到通知邮件,可以将收件地址\ -设置为一个邮件列表。如果选择“Send From Author”,邮件的发件者显示为提交者的\ -邮件地址,否则发件者为\ ``noreply@github.com``\ 。 +配置邮件通知,可以实现新提交推送至版本库时,发送通知邮件。在版本库的管理界面,选择“Service Hooks”中的Email进入邮件通知配置界面,如图3-15所示。配置界面很简单,写上邮件地址,选择激活即可。为了便于整个团队都能收到通知邮件,可以将收件地址设置为一个邮件列表。如果选择“Send From Author”,邮件的发件者显示为提交者的邮件地址,否则发件者为 ``noreply@github.com`` 。 .. figure:: /images/project-hosting/hooks-email.png :scale: 100 @@ -33,19 +22,10 @@ 图3-16:提交触发邮件通知 -.. _redmine-hook: - 和Redmine整合 --------------- -Redmine是一个开源的项目管理平台,用于项目的需求管理和缺陷跟踪。Redmine可以和\ -多种版本库(包括Git)整合,可以直接通过Web界面浏览Git提交,还实现了提交和问题\ -的关联。 - -Redmine需要周期性地扫描版本库,以便更新内置数据库及建立提交和问题的关联。\ -通常是以计划任务(crontab)的方式实现版本库的周期性扫描,这导致Redmine中\ -版本库更新会存在一定的延迟。GitHub提供的Redmine整合的钩子脚本能够在GitHub\ -版本库更新后,通过WebService触发Redmine主动扫描Git版本库获取更新。 +Redmine是一个开源的项目管理平台,实现需求管理和缺陷跟踪,并整合了版本库浏览和关联功能。Redmine通常以计划任务方式检查版本库更新,即版本更新反映到Redmine要有一定的延迟,GitHub提供的Redmine整合的钩子脚本能够在GitHub版本库更新后,通过WebService触发Redmine主动检查版本库更新。 GitHub提供的Redmine整合的配置界面如图3-17所示。 @@ -54,9 +34,7 @@ GitHub提供的Redmine整合的配置界面如图3-17所示。 图3-17:与Redmine整合 -图3-17中的地址是Redmine部署的URL地址,项目ID是Redmine中的相关项目(如果不填写\ -则更新所有项目),而“Api Key”并非GitHub项目中配置的Api Key,而是Redmine中为\ -版本库更新配置的全局Api Key。相应的Redmine配置界面如图3-18所示。 +图3-17中的地址是Redmine部署的URL地址,项目ID是Redmine中的相关项目(如果不填写则更新所有项目),而“Api Key”并非GitHub项目中配置的Api Key,而是Redmine中为版本库更新配置的全局Api Key,相应的Redmine配置界面如图3-18所示。 .. figure:: /images/project-hosting/redmine-api-key.png :scale: 100 diff --git a/03-project-hosting/050-homepage.rst b/03-project-hosting/050-homepage.rst index 45e6de8..b119358 100644 --- a/03-project-hosting/050-homepage.rst +++ b/03-project-hosting/050-homepage.rst @@ -1,35 +1,23 @@ -.. _homepage: - 建立主页 ================= -很多开源项目托管平台都支持为托管的项目建立主页,但主页的维护方式都没有GitHub\ -这么酷。大多数托管平台无非是开放一个FTP或类似服务,用户把制作好的网页或脚本\ -上传了事,而在GitHub用户通过创建特殊名称的Git版本库或在Git库中建立特别的分支\ -实现对主页的维护。 - -.. _user-homepage: +很多开源项目托管平台都支持为托管的项目建立主页,但主页的维护方式都没有GitHub这么酷。大多数托管平台无非是开放一个FTP或类似服务,用户把制作好的网页或脚本上传了事,而GitHub采用创建特殊名称的Git版本库或在Git库中建立特别的分支实现主页的创建。 创建个人主页 -------------- -GitHub 为每一个用户分配了一个二级域名\ ``.github.io``\ ,用户为自己\ -的二级域名创建主页很容易,只要在托管空间下创建一个名为\ ``.github.io``\ -的版本库,向其\ ``master``\ 分支提交网站静态页面即可,其中网站首页为\ -``index.html``\ 。下面以\ ``gotgithub``\ 用户为例介绍如何创建个人主页。 - -* 用户\ ``gotgithub``\ 创建一个名为\ ``gotgithub.github.io``\ 的Git版本库。 +为自己在GitHub的账号创建主页很容易,只要在托管空间下创建一个名为 ``.github.com`` 的版本库,在其中提交网站页面即可。以 ``gotgithub`` 用户为例。 - 在GitHub上创建版本库的操作,参见“第3.1节 :ref:`new-project`\ ”。 +* 创建一个名为 ``gotgithub.github.com`` 的Git版本库。 * 在本地克隆新建立的版本库。 :: - $ git clone git@github.com:gotgithub/gotgithub.github.io.git - $ cd gotgithub.github.io/ + $ git clone git@github.com:gotgithub/gotgithub.github.com.git + $ cd gotgithub.github.com/ -* 在版本库根目录中创建文件\ ``index.html``\ 作为首页。 +* 在版本库根目录中创建文件 ``index.html`` 作为首页。 :: @@ -48,51 +36,27 @@ GitHub 为每一个用户分配了一个二级域名\ ``.github.io``\ $ git push origin master -* 访问网址: http://gotgithub.github.io/ 。 +* 访问网址: http://gotgithub.github.com/ 。 - 最多等待10分钟,GitHub就可以完成新网站的部署。网站完成部署后版本库\ - 的所有者会收到邮件通知。 - - 还有要注意访问用户二级域名的主页要使用HTTP协议非HTTPS协议。 - -.. _project-homepage: + 最多等待10分钟,GitHub就可以完成新网站的部署。注意个人首页使用HTTP协议非HTTPS协议。 创建项目主页 --------------- -如前所述,GitHub会为每个账号分配一个二级域名\ ``.github.io``\ -作为用户的首页地址。实际上还可以为每个项目设置主页,项目主页也通过\ -此二级域名进行访问。 - -例如\ ``gotgithub``\ 用户创建的\ ``helloworld``\ 项目如果启用了项目主页,\ -则可通过网址\ ``http://gotgithub.github.io/helloworld/``\ 访问。 +GitHub会为每个用户分配一个子域名作为用户主页,同样用户创建的每一个项目也会在用户主页下创建一个子网站。例如 ``gotgithub`` 用户创建的 ``helloworld`` 项目经过简单的定制,会在地址 ``http://gotgithub.github.com/helloworld/`` 下创建项目首页。为项目建立自定义项目首页只需要在项目版本库中创建一个名为 ``gh-pages`` 的分支,并把网页提交到该分支即可。 -为项目启用项目主页很简单,只需要在项目版本库中创建一个名为\ ``gh-pages``\ -的分支,并向其中添加静态网页即可。也就是说如果项目的Git版本库中包含了名为\ -``gh-pages``\ 分支的话,则表明该项目提供静态网页构成的主页,可以通过网址\ -``http://.github.io/``\ 访问到。 - -下面以用户\ ``gotgithub``\ 的项目\ ``helloworld``\ 为例,介绍如何维护项目主页。 - -如果本地尚未从GitHub克隆\ ``helloworld``\ 版本库,执行如下命令。 +如果本地尚未建立 ``helloworld`` 版本库克隆,执行如下命令。 :: $ git clone git@github.com:gotgithub/helloworld.git $ cd helloworld -当前版本库只有一个名为\ ``master``\ 的分支,如果直接从\ ``master``\ 分支创建\ -``gh-pages``\ 分支操作非常简单,但是作为保存网页的\ ``gh-pages``\ 分支中的内容\ -和\ ``master``\ 分支中的可能完全不同。如果不希望\ ``gh-pages``\ 分支继承\ -``master``\ 分支的历史和文件,即想要创建一个干净的\ ``gh-pages``\ 分支,\ -需要一点小技巧。 - -若使用命令行创建干净的\ ``gh-pages``\ 分支,可以从下面三个方法任选一种。 +当前版本库只有一个名为 ``master`` 的分支,如果直接从 ``master`` 分支创建 ``gh-pages`` 分支操作非常简单,但是作为保存网页的 ``gh-pages`` 分支中的内容和 ``master`` 分支中的完全不同。如果不希望 ``gh-pages`` 分支继承 ``master`` 分支的历史和文件,即想要创建一个干净的 ``gh-pages`` 分支,需要一点小技巧。可以从下面两个方法任选一种。 -第一种方法用到两个Git底层命令:\ ``git write-tree``\ 和\ ``git commit-tree``\ 。\ -步骤如下: +第一种方法用到两个Git底层命令: ``git write-tree`` 和 ``git commit-tree`` 。步骤如下: -* 基于\ ``master``\ 分支建立分支\ ``gh-pages``\ 。 +* 基于 ``master`` 分支建立分支 ``gh-pages`` 。 :: @@ -104,35 +68,34 @@ GitHub 为每一个用户分配了一个二级域名\ ``.github.io``\ $ rm .git/index -* 创建项目首页\ ``index.html``\ 。 +* 创建项目首页 ``index.html`` 。 :: $ printf "hello world.\n" > index.html -* 添加文件\ ``index.html``\ 到暂存区。 +* 添加文件 ``index.html`` 到暂存区。 :: $ git add index.html -* 用Git底层命令创建新的根提交,并将分支\ ``gh-pages``\ 重置。 +* 用Git底层命令创建新的根提交,并将分支 ``gh-pages`` 重置。 :: $ git reset --hard $(echo "branch gh-pages init." | git commit-tree $(git write-tree)) -* 执行推送命令,在GitHub远程版本库创建分支\ ``gh-pages``\ 。 +* 执行推送命令,在GitHub远程版本库创建分支 ``gh-pages`` 。 :: - $ git push -u origin gh-pages + $ git push origin gh-pages -第二种方法用到Git底层命令:\ ``git symbolic-ref``\ 。步骤如下: +第二种方法用到Git底层命令: ``git symbolic-ref`` 。步骤如下: -* 用\ ``git symbolic-ref``\ 命令将当前工作分支由\ ``master``\ 切换到一个尚不\ - 存在的分支\ ``gh-pages``\ 。 +* 用 ``git symbolic-ref`` 命令将当前工作分支由 ``master`` 切换到一个尚不存在的分支 ``gh-pages`` 。 :: @@ -144,240 +107,109 @@ GitHub 为每一个用户分配了一个二级域名\ ``.github.io``\ $ rm .git/index -* 创建项目首页\ ``index.html``\ 。 - - :: - - $ printf "hello world.\n" > index.html - -* 添加文件\ ``index.html``\ 到暂存区。 - - :: - - $ git add index.html - -* 执行提交。提交完毕分支\ ``gh-pages``\ 完成创建。 - - :: - - $ git commit -m "branch gh-pages init." - -* 执行推送命令,在GitHub远程版本库创建分支\ ``gh-pages``\ 。 - - :: - - $ git push -u origin gh-pages - -第三种方法没有使用任何Git底层命令,是从另外的版本库获取提交建立分支。\ -操作如下: - -* 在\ ``helloworld``\ 版本库之外创建另外一个版本库,例如\ ``helloworld-web``\ 。 - - :: - - $ git init ../helloworld-web - $ cd ../helloworld-web - -* 在\ ``helloworld-web``\ 版本库中创建主页文件\ ``index.html``\ 。 +* 创建项目首页 ``index.html`` 。 :: $ printf "hello world.\n" > index.html -* 添加文件\ ``index.html``\ 到暂存区。 +* 添加文件 ``index.html`` 到暂存区。 :: $ git add index.html -* 执行提交。 - - 实际提交到\ ``master``\ 分支,虽然提交说明中出现的是\ ``gh-pages`` \。 +* 执行提交。提交完毕分支 ``gh-pages`` 完成创建。 :: - $ git commit -m "branch gh-pages init." + $ git commit --m "branch gh-pages init." -* 切换到\ ``helloworld``\ 版本库目录。 +* 执行推送命令,在GitHub远程版本库创建分支 ``gh-pages`` 。 :: - $ cd ../helloworld + $ git push origin gh-pages -* 从\ ``helloworld-web``\ 版本库获取提交,并据此创建\ ``gh-pages``\ 分支。 +无论哪种方法,一旦在GitHub远程版本库中创建分支 ``gh-pages`` ,项目的主页就已经建立。稍后(不超过10分钟),用浏览器访问下面的地址即可看到刚刚提交的项目首页。 - :: - - $ git fetch ../helloworld-web - $ git checkout -b gh-pages FETCH_HEAD - - -* 执行推送命令,在GitHub远程版本库创建分支\ ``gh-pages``\ 。 - - :: +* http://gotgithub.github.com/helloworld/ - $ git push -u origin gh-pages - - -无论哪种方法,一旦在GitHub远程版本库中创建分支\ ``gh-pages``\ ,项目的主页\ -就已经建立。稍后(不超过10分钟),用浏览器访问下面的地址即可看到刚刚提交的\ -项目首页: http://gotgithub.github.io/helloworld/ 。 - -除了以上通过命令行创建\ ``gh-pages``\ 分支为项目设定主页之外,GitHub还提供\ -了图形操作界面。如图3-19所示。 +除了以上用命令行方式创建 ``gh-pages`` 分支的方式为项目设定主页外,GitHub还在项目管理界面还提供了图形操作界面。如图3-19所示。 .. figure:: /images/project-hosting/github-pages.png :scale: 100 图3-19:项目管理页面中的GitHub Pages选项 -当在项目管理页面中勾选“GitHub Pages”选项,并按照提示操作,会自动在项目版本库\ -中创建\ ``gh-pages``\ 分支。然后执行下面命令从版本库检出\ ``gh-pages``\ 分支,\ -对项目主页进行相应定制。 +当在项目管理页面中勾选”GitHub Pages“选项,并按照提示操作,自动在项目版本库中创建 ``gh-pages`` 分支。然后执行下面命令从版本库检出 ``gh-pages`` 分支,对项目主页进行相应定制。 :: + $ cd helloworld $ git fetch - $ git checkout gh-pages - -.. _dedicate-domain: + $ git clone -b gh-pages origin/gh-pages 使用专有域名 --------------- -无论是用户主页还是项目主页,除了使用\ ``github.com``\ 下的二级域名访问之外,\ -还可以使用专有域名。实现起来也非常简单,只要在\ ``master``\ 分支(用户主页\ -所在版本库)或\ ``gh-pages``\ 分支(项目版本库)的根目录下检入一个名为\ -``CNAME``\ 的文件,内容为相应的专有域名。当然还要更改专有域名的域名解析,\ -使得该专有域名的IP地址指向相应的GitHub二级域名的IP地址。 +无论是用户主页还是项目主页,除了使用 ``github.com`` 下的子域名访问之外,还可以使用指定的专有域名。实现起来也非常简单,只要在 ``master`` 分支(用户主页所在版本库)或 ``gh-pages`` 分支(项目版本库)的根目录下检入一个名为 ``CNAME`` 的文件,内容为相应的专有域名。 -例如\ ``worldhello.net``\ [#]_\ 是我的个人网站,若计划将网站改为由GitHub托管,\ -并由账号\ ``gotgit``\ 通过个人主页提供服务,可做如下操作。 +例如用户拥有的专有域名为 ``example.com`` ,希望访问 ``example.com`` 时实际得到的是 ``gotgithub.github.com`` 网页的内容。只需进行如下操作: -首先按照前面章节介绍的步骤,为账号\ ``gotgit``\ 设置账户主页。 +* 在GitHub的 ``gotgithub`` 账户的 ``gotgithub.github.com`` 版本库的根目录下添加文件 ``CNAME`` ,文件内容为: ``example.com`` 。 +* 然后将域名 ``example.com`` 的IP指向 ``gotgithub.github.com`` 的IP地址(注意不是 ``github.com`` 的IP地址)。 -1. 在账户\ ``gotgit``\ 下创建版本库\ ``gotgit.github.io``\ 以维护该账号主页。 +设置完成后,访问 ``example.com`` 即可看到 ``gotgithub`` 用户在GitHub的个人主页。访问 ``gotgithub.github.com`` 网站亦会重定向到 ``example.com`` 。 - 地址: https://github.com/gotgit/gotgit.github.io/ - -2. 将网站内容提交并推送到该版本库\ ``master``\ 分支中。 - - 即在\ ``gotgit.github.io``\ 版本库的根目录下至少包含一个首页文件,如\ - ``index.html``\ 。还可以使用下节将要介绍到的 Jekyll 技术,让网页有统一的\ - 显示风格,此时首页文件可能并非一个完整的HTML文档,而是套用了页面模版。 - -3. 至此当访问网址\ http://gotgit.github.io\ 时,会将账号\ ``gotgit``\ - 的版本库\ ``gotgit.github.io``\ 中的内容作为网站内容显示出来。 - -接下来进行如下操作,使得该网站能够使用专有域名\ ``www.worldhello.net``\ -提供服务。 - -1. 在账号\ ``gotgit``\ 的版本库\ ``gotgit.github.io``\ 根目录下添加文件\ - ``CNAME``\ ,文件内容为:\ ``www.worldhello.net``\ 。 - - 参见: https://github.com/gotgit/gotgit.github.io/blob/master/CNAME - -2. 然后更改域名\ ``www.worldhello.net``\ 的IP地址,指向域名\ ``gotgit.github.io``\ - 对应的IP地址(注意不是\ ``github.com``\ 的IP地址)。 - - 完成域名的DNS指向后,可试着用\ ``ping``\ 或\ ``dig``\ 命令确认域名\ - ``www.worldhello.net``\ 和\ ``gotgit.github.io``\ 指向同一IP地址。 - - :: - - $ dig @8.8.8.8 -t a www.worldhello.net - ... - ; ANSWER SECTION: - www.worldhello.net. 81078 IN A 204.232.175.78 - - $ dig @8.8.8.8 -t a gotgit.github.io - ... - ; ANSWER SECTION: - gotgit.github.io. 43200 IN A 204.232.175.78 - -设置完成后用浏览器访问 http://www.worldhello.net/ 即可看到由账号\ ``gotgit``\ -的版本库\ ``gotgit.github.io``\ 维护的页面。若将域名\ ``worldhello.net``\ -(不带www前缀)也指向IP地址\ ``204.232.175.78``\ ,则访问网址\ -http://worldhello.net/\ 会发现GitHub体贴地将该网址重定向到正确的地址\ -http://www.worldhello.net/\ 。 - -在账号\ ``gotgit``\ 下的其他版本库,若包含了\ ``gh-pages``\ 分支,亦可由域名\ -``www.worldhello.net``\ 访问到。 - -* 网址 http://www.worldhello.net/doc 实际对应于版本库 `gotgit/doc `_ 。 -* 网址 http://www.worldhello.net/gotgit 实际对应于版本库 `gotgit/gotgit `_ 。 -* 网址 http://www.worldhello.net/gotgithub 实际对应于版本库 `gotgit/gotgithub `_ 。 - - -.. _jekyll: +看一个实际的例子: http://github.com/mojombo/mojombo.github.com/ → http://tom.preston-werner.com/ 。 使用Jekyll维护网站 ------------------------- -Jekyll是一个支持Textile、Markdown等标记语言的静态网站生成软件,还支持博客和\ -网页模版,由Tom Preston-Werner(GitHub创始人之一)开发。Jekyll用Ruby语言实现,\ -项目在GitHub的托管地址: http://github.com/mojombo/jekyll/ ,专有的URL地址为:\ -http://jekyllrb.com/\ 。 +Jekyll是由Tom Preston-Werner(GitHub创始人之一)开发的静态网站生成软件,支持博客及网页模版。使用Jekyll,可以直接使用Markdown或其他标记语言撰写页面及博客,当GitHub托管的版本库更新后,GitHub会自动运行Jekyll将标记语言撰写的文件转换为网页。 -GitHub为用户账号或项目提供主页服务,会从相应版本库的\ ``master``\ 分支或\ -``gh-pages``\ 分支检出网页文件,然后执行 Jekyll 相应的命令对网页进行编译。\ -因此在设计GitHub的用户主页和项目主页时都可以利用Jekyll,实现用Markdown等标记\ -语言撰写网页及博客,并用页面模版实现网页风格的统一。 - -安装Jekyll最简单的方法是通过RubyGems安装,会自动将Jekyll依赖的\ -directory_watcher、liquid、open4、maruku和classifier等Gem包一并安装。 +Jekyll用Ruby语言开发,项目在GitHub的托管地址: http://github.com/mojombo/jekyll/ ,专有的URL地址为: http://jekyllrb.com/ 。安装Jekyll最简单的方法是通过RubyGems安装,会自动将Jekyll依赖的directory_watcher、liquid、open4、maruku和classifier等Gem包一并安装。 :: $ gem install jekyll -如果安装过程因编译扩展模组遇到错误,可能是因为尚未安装所需的头文件,需要进行如下操作: +如果安装过程因编译扩展模组遇到错误,可能是因为尚未安装所需的头文件。对于Debian Linux、Ubuntu等可以用如下方法安装所需软件包: -* 对于Debian Linux、Ubuntu等可以用如下方法安装所需软件包: +:: - :: - - $ sudo apt-get install ruby1.8-dev + $ sudo apt-get install ruby1.8-dev -* 如果是Red Hat、CentOS或Fedora等系统,使用如下命令安装: +如果是Red Hat、CentOS或Fedora等系统,使用如下命令安装: - :: - - $ sudo yum install ruby-devel +:: -* 对于Mac OSX,可能需要更新RubyGems,如下: + $ sudo yum install ruby-devel - :: - - $ sudo gem update --system +对于Mac OSX,可能需要更新RubyGems,如下: + +:: -Jekyll安装完毕,执行下面的命令显示软件版本: + $ sudo gem update --system + +安装完毕,执行下面的命令显示Jekyll的版本: :: $ jekyll -v Jekyll 0.11.0 -要学习如何用Jekyll设计网站,可以先看一下作者Tom Preston-Werner在GitHub上的\ -个人网站是如何用Jekyll制作出来的。 +先来看一下作者Tom Preston-Werner在GitHub上的个人网站,看看是如何用Jekyll制作出来的。 -克隆版本库: +先克隆版本库: :: $ git clone git://github.com/mojombo/mojombo.github.com.git - -版本库包含的文件如下: - -:: - $ cd mojombo.github.com - $ ls -F - CNAME _config.yml _posts/ css/ index.html - README.textile _layouts/ atom.xml images/ random/ -版本库根目录下的\ ``index.html``\ 文件不是一个普通的HTML文件,而是使用Liquid\ -模版语言\ [#]_\ 定义的页面。 +版本库根目录下的 ``index.html`` 文件不是一个完整的HTML文件,而是套用了模版(Liquid格式模版)的页面,对其关键内容添加行号显示如下: :: @@ -396,45 +228,13 @@ Jekyll安装完毕,执行下面的命令显示软件版本: ... 63 -为方便描述为内容添加了行号,说明如下: - -* 第1-4行是YAML格式的文件头,设定了该文件所使用的模版文件及模版中要用到的变量。 - - 凡是设置有YAML文件头的文件(目录\ ``_layouts``\ 除外)无论文件扩展名是什么,\ - 都会在Jekyll编译时进行转换。若源文件由Markdown等标记语言撰写(扩展名为\ ``.md``\ 、\ - ``.textile``\ 等),Jekyll还会将编译后的文件还将以扩展名\ ``.html``\ 来保存。 - -* 其中第2行含义为使用default模版。 +第1-4行是YAML格式的文件头,确定模版的对应关系并设定相关属性。凡是设置有YAML文件头的文件(目录 ``_layouts`` 等除外)无论文件扩展名为何,都会在Jekyll编译时转换为对应的HTML文件。其中第2行含义为使用default模版(对应于的模版文件为 ``_layouts/default.html`` ),第3行设定本页面的标题。 - 对应的模版文件为\ ``_layouts/default.html``\ 。 +第6行开始的内容绝大多数是标准的HTML语法,其中夹杂少量liquid模版特有的语法。有着liquid或其他模版编程经验的用户,不难理解其中第9行和第11行出现的由”{%“和”%}“标识的指令是一个循环指令(for循环)用于逐条对博客进行相关操作,而第10行中由”{{“和”}}“标识的表达式则用于显示博文的日期、链接和标题。 -* 第3行设定本页面的标题。 +根目录下的 ``atom.xml`` 文件亦套用 ``default`` 模版。 - 在模版文件\ ``_layouts/default.html``\ 中用\ ``{{ page.title }}``\ 语法嵌入\ - 所设置的标题。下面是模版文件中部分内容: - - :: - - - - {{ page.title }} - -* 第6行开始的内容绝大多数是标准的HTML语法,其中夹杂少量Liquid模版特有的语法。 - -* 第9行和第11行,对于有着Liquid或其他模版编程经验的用户,不难理解其中出现的由\ - “{%”和“%}”标识的指令是一个循环指令(for循环),用于逐条对博客进行相关操作。 - -* 第10行中由“{{”和“}}”标识的表达式则用于显示博文的日期、链接和标题。 - -非下划线(_)开头的文件(包括子目录中文件),如果包含YAML文件头,就会使用Jekyll\ -进行编译,并将编译后的文件复制到目标文件夹(默认为\ ``_site``\ 目录)下。\ -对于包含YAML文件头并用标记语言Markdown等撰写的文件,还会将编译后的文件以\ -``.html``\ 扩展名保存。而以下划线开头的文件和目录有的直接忽略不予处理(如\ -``_layouts``\ 、\ ``_site``\ 目录等),有的则需要特殊处理(如\ ``_post``\ 目录)。 - -目录\ ``_post``\ 用于保存博客条目,每个博客条目都以\ ``--
-``\ -格式的文件名命名。扩展名为\ ``.md``\ 的为Markdown格式,扩展名为\ ``.textile``\ -的为Textile格式。这些文件都包含类似的文件头: +目录 ``_post`` 下的文件是博客文章列表,每个博文都以 ``--
-`` 格式的文件名命名。扩展名为 ``.md`` 的为Markdown格式,扩展名为 ``.textile`` 的为Textile格式。这些文件都类似如下格式的文件头: :: @@ -443,32 +243,26 @@ Jekyll安装完毕,执行下面的命令显示软件版本: title: How I Turned Down $300,000 from Microsoft to go Full-Time on GitHub --- -即博客使用文件\ ``_layouts/post.html``\ 作为页面模版,而不是\ ``index.html``\ -等文件所使用的\ ``_layouts/default.html``\ 模版。这些模版文件都采用Liquid模版\ -语法。保存于\ ``_post``\ 目录下的博客文件编译后会以\ -``//
/.html``\ 文件名保存在输出目录中。 +在 ``_layouts`` 目录下定义网页模版,其中文件 ``_layouts/post.html`` 是博客用到的模版,而 ``_layouts/default.html`` 是默认模版。模版文件亦是liquid格式文件。 -在根目录下还有一个配置文件\ ``_config.yml``\ 用于覆盖Jekyll的默认设置,例如\ -本版本库中的设置。 +在根目录下还有一个配置文件 ``_config.yml`` 用于覆盖Jekyll的默认设置,例如本版本库中的设置。 :: markdown: rdiscount pygments: true -第1行设置使用rdiscount软件包作为Markdown的解析引擎,而非默认的Maruku。第2行开启\ -pygments支持。对于中文用户强烈建议通过配置文件\ ``_config.yml``\ 重设 markdown \ -解析引擎,默认的 Maruku 对中文支持不好,而使用 rdiscount 或 kramdown 均可。\ -关于该配置文件的更多参数详见Jekyll项目维基\ [#]_\ 。 +第1行设置使用rdiscount软件包作为Markdown的解析引擎,而非默认的Maruku。第2行开启pygments支持。关于该配置文件的详细介绍参见 `Jekyll项目维基`_ 。 + +.. _`Jekyll项目维基`: https://github.com/mojombo/jekyll/wiki/configuration -编译Jekyll编辑网站只需在根目录执行\ ``jekyll``\ 命令,下面的命令是GitHub更新\ -网站所使用的默认指令。 +编译Jekyll编辑网站只需在根目录执行 ``jekyll`` 命令,下面的命令是GitHub更新网站所使用的默认指令。 :: $ jekyll --pygments --safe -现在执行这条命令,就会将整个网站创建在目录\ ``_site``\ 下。 +现在执行这条命令,就会将整个网站创建在目录 ``_site`` 下。 如果没有安装Apache等Web服务器,还可以使用Jekyll的内置Web服务器。 @@ -485,18 +279,7 @@ pygments支持。对于中文用户强烈建议通过配置文件\ ``_config.yml 图3-20:Git Ready 网站 -你相信这是一个用Jekyll制作的网站么?看看该网站对应的IP,会发现其指向的正是GitHub。\ -研究GitHub上 `gitready`_ 用户托管的版本库,会发现\ ``en``\ 版本库的\ ``gh-pages``\ -分支负责生成\ ``gitready.com``\ 网站,\ ``de``\ 版本库的\ ``gh-pages``\ 分支负责\ -生成德文网站\ ``de.gitready.com``\ ,等等。而\ ``gitready``\ 版本库则是各种语种网站的汇总。 +你相信这是一个用Jekyll制作的网站么?看看该网站对应的IP,会发现其指向的正是GitHub。研究GitHub上 `gitready`_ 用户托管的版本库,会发现 ``en`` 版本库的 ``gh-pages`` 分支负责生成 ``gitready.com`` 网站, ``de`` 版本库的 ``gh-pages`` 分支负责生成德文网站 ``de.gitready.com`` ,等等。而 ``gitready`` 版本库则是各种语种网站的汇总。 .. _`gitready`: https://github.com/gitready -我的个人网站也使用Jekyll构建并托管在GitHub上,网址:\ http://www.worldhello.net/\ 。 - ----- - -.. [#] “Hello, world”最为程序员所熟知,2002年申请不到helloworld相关域名便\ - 退而求其次,申请了 worldhello.net。 -.. [#] http://liquidmarkup.org/ -.. [#] https://github.com/mojombo/jekyll/wiki/configuration diff --git a/03-project-hosting/index.rst b/03-project-hosting/index.rst index 9e8e67c..626feed 100644 --- a/03-project-hosting/index.rst +++ b/03-project-hosting/index.rst @@ -1,5 +1,3 @@ -.. _hosting: - 项目托管 ******************** 本章介绍如何在GitHub上创建一个新项目,包括创建版本库及为项目设计主页等。 diff --git a/04-work-with-others/010-fork-and-pull.rst b/04-work-with-others/010-fork-and-pull.rst index 75397d3..cee0ecc 100644 --- a/04-work-with-others/010-fork-and-pull.rst +++ b/04-work-with-others/010-fork-and-pull.rst @@ -1,47 +1,33 @@ -.. _fork-and-pull-request: - Fork + Pull模式 ==================== -参与GitHub中的项目开发,最常用和推荐的首选方式是“Fork + Pull”模式。在\ -“Fork + Pull”模式下,项目参与者不必向项目创建者申请提交权限,而是在自己的托管\ -空间下建立项目的派生(Fork)。 +参与GitHub中的项目开发,最常用和推荐的首选方式是“Fork + Pull”模式。在“Fork + Pull”模式下,项目参与者不必向项目创建者申请提交权限,而是在自己的托管空间下建立项目的派生(Fork)。 -如果一个开源项目派生出另外的项目,通常意味着项目的分裂和开发团队的削弱,\ -而GitHub中的项目派生则不会,而且正好相反,GitHub中的项目派生是项目壮大的体现。\ -所有的派生项目都会有链接指向原始项目,派生项目没有独立的缺陷追踪系统(ISSUE),\ -而是必须利用创建者本人的项目中的缺陷追踪系统。至于在派生项目中创建的提交,\ -可以非常方便地利用GitHub的Pull Request工具向原始项目的维护者发送Pull Request。 +如果一个开源项目产生派生出另外的项目,通常意味着项目的分裂和开发团队的削弱,而GitHub中的项目派生则不会,而且正好相反,GitHub中的项目派生是项目壮大的体现。所有的派生项目都会有链接指向原始项目,派生项目没有独立的缺陷追踪系统(ISSUE),而是必须利用创建者本人的项目中的缺陷追踪系统。至于在派生项目中创建的提交,可以非常方便的利用GitHub的Pull Request工具向原始项目的维护者发送Pull Request。 下面以GotGit版本库为例,介绍如何利用GitHub提供的Fork和Pull Request工具实现工作协同。 -.. _fork: - 版本库派生 ------------------ -GotGit版本库\ [#]_\ 用于维护《Git权威指南》一书的官网和勘误,下面演示的勘误表\ -修改是由王胜\ [#]_\ 通过GitHub之外的一个缺陷追踪平台报告的\ [#]_\ 。\ -他在报告中,甚至直接用GNU diff格式告诉我该如何修改。 +GotGit版本库 [#]_ 用于维护《Git权威指南》一书的官网和勘误,下面演示的勘误表修改是由王胜 [#]_ +通过GitHub之外的一个缺陷追踪平台报告的 [#]_ 。他在报告中,甚至直接用GNU diff格式告诉我该如何修改。 -下面就以用户gotgithub身份,访问版本库 https://github.com/gotgit/gotgit/ ,\ -添加新的勘误。如图4-1所示,gotgit项目在之前的示例中已经被我们关注但尚未Fork。 +下面就以用户gotgithub身份,访问版本库 https://github.com/gotgit/gotgit/ ,添加新的勘误。如图4-1所示,gotgit项目在之前的示例中已经被我们关注但尚未Fork。 -.. figure:: /images/work-with-others/gotgit-repo-before-fork.png +.. figure:: /images/work-with-others/gotgit-repo.png :scale: 100 图4-1:原gotgit项目 -点击项目名称右侧的Fork按钮,便在gotgithub用户自己的托管空间下创建项目派生,\ -派生项目版本库出现在版本库列表中,如图4-2。 +点击项目名称右侧的Fork按钮,便在gotgithub用户自己的托管空间下创建项目派生,派生项目版本库出现在版本库列表中,如图4-2。 .. figure:: /images/work-with-others/gotgit-in-repo-list.png :scale: 100 图4-2:gotgithub用户的项目列表 -访问派生后的版本库,会发现和派生前的几乎相同,除了没有缺陷跟踪(ISSUE),\ -以及标识了该项目派生之前的原路径等。如图4-3所示。 +访问派生后的版本库,会发现和派生前的几乎相同,除了没有缺陷跟踪(ISSUE),以及标识了该项目派生之前的原路径等。如图4-3所示。 .. figure:: /images/work-with-others/gotgit-repo-forked.png :scale: 100 @@ -64,13 +50,13 @@ GotGit版本库\ [#]_\ 用于维护《Git权威指南》一书的官网和勘误 $ git config user.name "Wang Sheng" $ git config user.email wangsheng@ossxp.com -* 编辑\ ``errata.mkd``\ 文件\ [#]_\ ,录入新发现的书中的文字错误。 +* 编辑 ``error.mkd`` 文件,录入新发现的书中的文字错误。 :: $ vi errata.mkd -* 对\ ``error.mkd``\ 的改动如下: +* 对 ``error.mkd`` 的改动如下: :: @@ -91,7 +77,7 @@ GotGit版本库\ [#]_\ 用于维护《Git权威指南》一书的官网和勘误 :: $ git add -u - $ git commit -m "Fixed #3: should be 项目, not 项." + $ git commit -m "Fixed #3: should be 项目, not 项." * 推送提交到GitHub。 @@ -99,22 +85,17 @@ GotGit版本库\ [#]_\ 用于维护《Git权威指南》一书的官网和勘误 $ git push -访问GitHub上的派生项目页面,会看到以用户wangsheng在\ ``master``\ 分支\ [#]_\ -创建的提交。如图4-4所示。 +访问GitHub上的派生项目页面,会看到以用户whangsheng创建的提交,如图4-4所示。 .. figure:: /images/work-with-others/gotgit-new-commit.png :scale: 100 图4-4:派生版本库中的新提交 -.. _pull-request: - Pull Request ------------------ -那么如何能够让gotgit原始项目的创建者知道这个派生项目及新的提交呢?GitHub提供的\ -工具就是“Pull Request”。注意到图4-3右上方“Pull Request”按钮了么?点击该按钮进入\ -Pull Request创建界面。 +那么如何能够让gotgit原始项目的创建者知道这个派生项目及新的提交呢?GitHub提供的工具就是“Pull Request”。注意到图4-4中标记的按钮了么?点击该按钮进入Pull Request创建界面。 在弹出的Pull Request创建界面中,点击菜单中的“Commits”,查看所包含的提交。如图4-5所示。 @@ -128,15 +109,14 @@ Pull Request创建界面。 .. figure:: /images/work-with-others/pull-request-form-file.png :scale: 100 - 图4-6:Pull Request包含的改动差异 + 图4-6:Pull Request包含的文件修改 -点击菜单中的“Preview Discussion”,填写Pull Request的标题和内容,完成Pull Request\ -的创建。如图4-7所示。 +点击菜单中的“Preview Discussion”,填写Pull Request的标题和内容,完成Pull Request的创建。如图4-7所示。 .. figure:: /images/work-with-others/pull-request-form-discuss.png :scale: 100 - 图4-7:Pull Request的提交界面 + 图4-7:Pull Request包含的文件差异 当Pull Request发出后,项目gotgit的开发者会收到通知邮件,如图4-8所示。 @@ -145,40 +125,31 @@ Pull Request创建界面。 图4-8:Pull Request的通知邮件 -点击邮件中的URL链接,以项目gotgit的开发者(如ossxp-com)身份登录,看到如图4-9\ -的视图。之所以看到有两个用户参与到此Pull Request,是因为Pull Request创建者和\ -提交的作者是不同的用户。图4-9下方的表单可以向Pull Request追加评论,或者关闭此\ -Pull Request。 +点击邮件中的URL链接,以项目gotgit的开发者(如ossxp-com)身份登录,看到如图4-9的视图。之所以看到有两个用户参与到此Pull Request,是因为Pull Request和提交是以不同用户身份创建的。图4-9下方的表单可以向Pull Request追加评论,或者关闭此Pull Request。 .. figure:: /images/work-with-others/pull-request-owner-view.png :scale: 100 图4-9:Pull Request接收者视图 -GitHub如果检测到Pull Request中包含的提交可以直接合并,会显示自动合并的提示信息,\ -点击图4-9中提示信息中的自动合并按钮,显示图4-10的自动合并对话框。 +GitHub如果检测到Pull Request中包含的提交可以直接合并,会显示自动合并的提示信息,点击图4-9中提示信息中的自动合并按钮,显示图4-10的自动合并对话框。 .. figure:: /images/work-with-others/pull-request-auto-merge.png :scale: 100 图4-10:Pull Request的通知邮件 -点击“Confirm Merge”按钮即完成Pull Request中所含提交的自动合并。自动合并完成后,\ -Pull Request页面下方会以评论的形式出现相关提示,并自动关闭Pull Request。\ -如图4-11所示。 +点击“Confirm Merge”按钮即完成Pull Request中所含提交的自动合并。自动合并完成后,Pull Request页面下方会以评论的形式出现相关提示,并自动关闭Pull Request。如图4-11所示。 .. figure:: /images/work-with-others/pull-request-closed.png :scale: 100 图4-11:Pull Request关闭 -.. _merge-by-hands: - 手工合并 ------------ -Pull Request提供的自动合并显示在提交日志中是什么样子的呢?以用户ossxp-com\ -身份检出版本库,会看到用户wangsheng的提交已经合并到版本库中。 +Pull Request提供的自动合并显示在提交日志中是什么样子的呢?以用户ossxp-com身份检出版本库,会看到用户wangsheng的提交已经合并到版本库中。 :: @@ -206,13 +177,9 @@ Pull Request提供的自动合并显示在提交日志中是什么样子的呢 | | Change font color for stronger text from red to brown. -可以看出GitHub的自动合并产生了一个合并提交,类似执行\ ``git merge --no-ff``\ -命令。也就是说即使用户wangsheng的提交是一个“快进式提交”(基于gotgit/gotgit\ -版本库最新提交所做的提交),也要产生一个合并提交。 +可以看出GitHub的自动合并产生了一个合并提交,类似执行 ``git merge --no-ff`` 命令。也就是说即使用户wangsheng的提交是一个“快进式提交”(基于gotgit/gotgit版本库最新提交所做的提交),也要产生一个合并提交。 -可能有人并不喜欢这种用\ ``--no-ff``\ 参数的非标准的合并方式,因为这种合并产生\ -了一个多余的提交,可能增加代码评审的负担。若要取消GitHub的自动合并也很简单,\ -因为Git无所不能: +可能有人并不喜欢这种用 ``--no-ff`` 参数的非标准的合并方式,因为这种合并产生了一个多余的提交,可能增加代码评审的负担。若要取消GitHub的自动合并也很简单,因为Git无所不能: :: @@ -221,9 +188,7 @@ Pull Request提供的自动合并显示在提交日志中是什么样子的呢 00c6c4bfab9824bd967440902ce87440f9e87852 $ git push -f # 强制推送回退的 master 分支 -下面就演示一下当收到他人的Pull Request后,该如何手动合并。实际上在很多情况下,\ -Pull Request所含提交有可能造成合并冲突,那样的话GitHub不再、也不能提供自动合并\ -功能,就必须采用手工合并的方式。 +下面就演示一下当收到他人的Pull Request后,该如何手动合并。实际上在很多情况下,Pull Request所含提交有可能造成合并冲突,那样的话GitHub不再、也不能提供自动合并功能,就必须采用手工合并的方式。 * 将Pull Request发出者的派生版本库添加为一个新的源。 @@ -252,7 +217,7 @@ Pull Request所含提交有可能造成合并冲突,那样的话GitHub不再 * [new branch] gh-pages -> gotgithub/gh-pages * [new branch] master -> gotgithub/master -* 现在除了本地分支\ ``master``\ 外,还有若干远程分支,如下: +* 现在除了本地分支 ``master`` 外,还有若干远程分支,如下: :: @@ -265,8 +230,7 @@ Pull Request所含提交有可能造成合并冲突,那样的话GitHub不再 remotes/origin/master -* 将远程分支\ ``remotes/gotgithub/master``\ (可简写为\ ``gotgithub/master``\ )\ - 合并到当前分支中。 +* 将远程分支 ``remotes/gotgithub/master`` (可简写为 ``gotgithub/master`` )合并到当前分支中。 :: @@ -299,17 +263,15 @@ Pull Request所含提交有可能造成合并冲突,那样的话GitHub不再 $ git push -.. _online-edit: -在线编辑 ---------- +简化的 Fork + Pull Request +-------------------------------- + +GitHub提供了一个快捷的“Fork + Pull Request”操作。在介绍该操作前,先介绍一下GitHub的在线编辑文件功能。例如以gotgithub用户登录GitHub,访问一下地址: -GitHub提供了在线编辑功能,这样可以无需克隆版本库、无需使用Git即可完成对版本库\ -中文件的修改,甚至可以在你的iPad甚至iPhone上完成对文件的修改。 +* https://github.com/gotgithub/gotgit/blob/master/errata.mkd -以gotgithub账户身份登录GitHub,访问之前派生而来的版本库gotgithub/gotgit\ -中的文件,例如文件\ ``errata.md``\ [#]_\ ,会看到其中一个“Edit this file”\ -的按钮,如图4-12所示。 +即浏览派生的版本库 ``gotgithub/gotgit`` 中的文件 ``errata.mkd`` ,会看到其中一个“Edit this file”的按钮,如图4-12所示。 .. figure:: /images/work-with-others/edit-this-file-btn.png @@ -317,98 +279,45 @@ GitHub提供了在线编辑功能,这样可以无需克隆版本库、无需 图4-12:浏览自己版本库中文件 -点击图4-12中的“Edit this file”按钮,开始在线编辑文件\ ``errata.md``\ ,\ -编辑器还支持语法加亮,如图4-13所示。 +点击图4-12中的“Edit this file”按钮,开始在线编辑文件 ``errata.mkd`` ,编辑器还支持语法加亮,如图4-13所示。 .. figure:: /images/work-with-others/edit-this-file-form.png :scale: 100 图4-13:编辑文件 -.. _quick-fork-edit-pull-request: +到目前,我们已经了解了GitHub的三大武器:Fork、Pull Request和在线编辑。下面就介绍一下对于最常用的“Fork + Pull Request”操作,GitHub是如何完美地将三大武器整合在一起,提供最快捷和最自然的操作方式。即GitHub对于他人版本库文件(无权修改)提供了一个“Fork and edit this file”的按钮,将三大武器一勺烩。 -简化的 Fork + Pull Request --------------------------------- +访问他人版本库(尚未在自己空间派生)中的文件,例如访问下面网址: -到目前,我们已经了解了GitHub的三大武器:Fork、Pull Request和在线编辑。对于\ -最常用的“Fork + Pull Request”操作,GitHub还提供了一个快捷模式。即GitHub对于\ -无权更改的他人版本库中的文件,提供了一个类似在线编辑的按钮,名为\ -“Fork and edit this file”按钮,自动完成版本库派生和在线编辑,即将三大武器一勺烩。 +* https://github.com/ossxp-com/hello-world/blob/master/README -访问他人版本库(尚未在自己空间派生)中的文件,例如访问下面地址:\ -http://git.io/hello-world-makefile\ [#]_\ 。显示他人(ossxp-com)版本库\ -``hello-world``\ 中的\ ``src/Makefile``\ 文件,如图4-14所示。 +显示他人(ossxp-com)版本库 ``hello-world`` 中的 ``README`` 文件,如图4-14所示。 .. figure:: /images/work-with-others/fork-and-edit-btn.png :scale: 100 - 图4-14:浏览他人版本库中文件 + 图4-14:浏览让人版本库中文件 -点击图4-14中的“Fork and edit this file”按钮,会自动在自己托管空间创建派生\ -版本库,并开始在线编辑文件\ ``src/Makefile``\ ,如图4-15所示。 +点击图4-14中的“Fork and edit this file”按钮,会自动在自己托管空间创建派生版本库,并开始在线编辑文件 ``errata.mkd`` ,如图4-15所示。 .. figure:: /images/work-with-others/fork-and-edit-form.png :scale: 100 图4-15:派生并编辑文件 -文件修改完毕,点击“Propose File Change”按钮,会将改动作提交到派生的版本库中,\ -并马上开启一个新的Pull Request。如图4-16所示。 +文件修改完毕,点击“Propose File Change”按钮,会将改动作提交到派生的版本库中,并马上开启一个新的Pull Request。如图4-16所示。 .. figure:: /images/work-with-others/fork-and-edit-pull-request.png :scale: 100 图4-16:编辑完毕自动开启Pull Request -点击“Send pull request”按钮完成Pull Request的创建。如果仔细查看图4-16,会发现\ -Pull Request所包含的修改发生在\ ``gotgithub/hello-world``\ 派生版本库中的\ -``patch-1``\ 分支中,并非通常的\ ``master``\ 分支。 - -原版本库\ ``ossxp-com/hello-world``\ 的开发者会收到一封邮件,通知有新的\ -Pull Request,如下所示(前四行为信头): - -:: - - From: GotGitHub - Date: 2011/12/17 - Subject: [hello-world] Bugfix: build target when version.h changed. (#1) - To: Jiang Xin - - - Without this fix, when version changed only version.h update, target rebuild needs a second `make`. - - You can merge this Pull Request by running: - - git pull https://github.com/gotgithub/hello-world patch-1 - - Or you can view, comment on it, or merge it online at: - - https://github.com/ossxp-com/hello-world/pull/1 - - -- Commit Summary -- - - * Bugfix: build target when version.h changed. - - -- File Changes -- - - M src/Makefile (3) - - -- Patch Links -- - - https://github.com/ossxp-com/hello-world/pull/1.patch - https://github.com/ossxp-com/hello-world/pull/1.diff - - --- - Reply to this email directly or view it on GitHub: - https://github.com/ossxp-com/hello-world/pull/1 - -版本库\ ``ossxp-com/hello-world``\ 的管理员既可以通过GitHub提供的图形化界面\ -完成对 Pull Request 的审核和合并,也可以在命令行下完成。正如邮件中所述若使用\ -命令行,操作如下: +如果仔细查看图4-16,会发现此次派生并修改发生在 ``gotgithub/hello-world`` 派生版本库中的 ``patch-1`` 分支中,并非通常的 ``master`` 分支。因此当 ``hello-world`` 原始版本库的管理员收到此Pull Request并打算手工合并的话,要注意合并正确的分支。例如使用如下命令: :: - $ git pull https://github.com/gotgithub/hello-world patch-1 + $ git merge gotgithub/patch-1 ---- @@ -416,10 +325,3 @@ Pull Request,如下所示(前四行为信头): .. [#] https://github.com/gotgit/gotgit/ .. [#] https://github.com/wangsheng/ .. [#] http://redmine.ossxp.com/redmine/issues/161 -.. [#] 版本库 gotgit/gotgit 已将勘误文件重命名为\ ``errata.md``\ 。 -.. [#] 版本库 gotgit/gotgit 原\ ``master``\ 分支内容已转移至\ ``gh-pages``\ - 分支,通过GitHub提供的网站部署机制完成网页的编译和部署。 -.. [#] 版本库 gotgit/gotgit 已重构。分支\ ``gh-pages``\ 中文件\ ``errata.md``\ - 文件来自于原\ ``master``\ 分支的\ ``errata.mkd``\ 文件,地址:\ - https://github.com/gotgithub/gotgit/blob/gh-pages/errata.md 。 -.. [#] 即地址 https://github.com/ossxp-com/hello-world/blob/master/src/Makefile 。 diff --git a/04-work-with-others/020-shared-repo.rst b/04-work-with-others/020-shared-repo.rst index 9c37233..973f2b1 100644 --- a/04-work-with-others/020-shared-repo.rst +++ b/04-work-with-others/020-shared-repo.rst @@ -1,61 +1,42 @@ -.. _shared_repo: - 共享版本库 =============== -除了独具特色的“Fork + Pull”的分布式工作模式,GitHub同样支持传统的集中式协同\ -工作模式。 - -.. _collaborators: +除了独具特色的“Fork + Pull”的分布式工作模式,GitHub同样支持传统的集中式协同工作模式。 版本库授权 ----------------- -GitHub可以通过多种途径为版本库授权,让版本库成为多人共享的版本库,从而让项目\ -管理者围绕项目创建一个核心开发团队。下面以gotgithub账号下的helloworld版本库\ -为例,介绍如何设置版本库的多人共享。 +GitHub可以通过多种途径为版本库授权,让版本库成为多人共享的版本库,从而让项目管理者围绕项目创建一个核心开发团队。下面以gotgithub账号下的helloworld版本库为例,介绍如何设置版本库的多人共享。 -进入\ ``gotgithub/helloworld``\ 项目的管理界面,点击左侧导航条中的\ -“Collaborators”,可以查看及添加项目的合作者,如图4-17所示。 +进入 ``gotgithub/helloworld`` 项目的管理界面,点击左侧导航条中的“Collaborators”,可以查看及添加项目的合作者,如图4-17所示。 .. figure:: /images/work-with-others/collaborators.png :scale: 100 图4-17:添加项目合作者 -图4-17为项目添加了两个合作者:supergirl和incredible。添加到项目当中的合作者\ -会收到通知邮件,告知已经被加入到相应的项目当中。当新加入的项目合作者,如\ -incredible,登录GitHub,在仪表板的版本库列表中会看到源自gotgithub用户的版本库,\ -如图4-18所示。 +图4-17为项目添加了两个合作者:ossxp-com和jiangxin。添加到项目当中的合作者会收到通知邮件,告知已经被加入到相应的项目当中。当新加入的项目合作者,如jiangxin,登录GitHub,在仪表板的版本库列表中会看到源自gotgithub用户的版本库,如图4-18所示。 .. figure:: /images/work-with-others/prj-list-of-collab.png :scale: 100 图4-18:合作者项目列表 -从图4-18可以看出GitHub用户incredible自己创建的项目托管在自己的空间下,而作为\ -合作者参与的项目仍然托管在原创建者(gotgithub)的空间下,这一点明显和派生\ -(Fork)而来的项目不同。图4-19是以incredible登录GitHub访问\ -``gotgithub/helloworld``\ 的界面。 +从图4-18可以看出GitHub用户jiangxin自己创建的项目托管在自己的空间下,而作为合作者参与的项目仍然托管在原创建者(gotgithub)的空间下,这一点明显和项目分支(Fork)不同。图4-19是以jiangxin登录GitHub访问 ``gotgithub/helloworld`` 的界面。 -.. figure:: /images/work-with-others/collab-view-helloworld.png +.. figure:: /images/work-with-others/jx-helloworld.png :scale: 100 图4-19:以合作者身份访问项目 -用户incredible对版本库\ ``gotgithub/helloworld``\ 拥有写入权限。和\ ``gotgithub``\ -用户稍有区别的是没有管理员权限。 - -.. _central-model: +用户jiangxin对版本库 ``gotgithub/helloworld`` 拥有写入权限。和 ``gotgithub`` 用户稍有区别的是没有管理员权限。 与传统集中式工作模式的异同 -------------------------------- -传统的集中式版本控制系统,如CVS、SVN,所有用户都访问同一个版本库。采用集中式\ -工作模式的GitHub用户也同样是访问同一版本库。 +传统的集中式版本控制系统,如CVS、SVN,所有用户都访问同一个版本库。采用集中式工作模式的GitHub用户同样也是访问同一版本库。 -对于由用户gotgithub创建的\ ``helloworld``\ 版本库,添加了合作者supergirl和\ -incredible,三个人克隆版本库使用如下命令。 +对于由用户gotgithub创建的 ``helloworld`` 版本库,添加了合作者ossxp-com和jiangxin,三个人克隆版本库使用如下命令。 * 用户 gotgithub 克隆版本库。 @@ -63,189 +44,165 @@ incredible,三个人克隆版本库使用如下命令。 gotgithub$ git clone https://gotgithub@github.com/gotgithub/helloworld.git -* 用户 supergirl 克隆版本库。 +* 用户 ossxp-com 克隆版本库。 :: - supergirl$ git clone https://supergirl@github.com/gotgithub/helloworld.git + ossxp-com$ git clone https://ossxp-com@github.com/gotgithub/helloworld.git -* 用户 incredible 克隆版本库。 +* 用户 jiangxin 克隆版本库。 :: - incredible$ git clone https://incredible@github.com/gotgithub/helloworld.git + jiangxin$ git clone https://jiangxin@github.com/gotgithub/helloworld.git -传统集中式版本控制系统,所有的提交历史数据都在唯一的版本库中,各个提交是\ -顺序进行的。为了防止多用户在提交时相互覆盖,集中式版本控制系统发明了很多方法 。\ -有的采用编辑锁的形式(如VSS),更改文件前对文件锁定,其他人禁止对文件进行\ -访问(甚至无法读取),完成修改并提交后,文件解锁。有的如SVN,允许多人同时\ -编辑同一文件,但只有先进行提交的才能成功,后提交的会遇到“过时”错误,必须先\ -获取版本库中的新增提交并和本地修改进行合并。即传统集中式版本控制系统,\ -提交时必须和唯一的版本库所在的服务器保持连接,而且提交有可能会失败。 +传统集中式版本控制系统,所有的提交历史数据都在唯一的版本库中,各个提交是顺序进行的。为了防止多用户在提交时相互覆盖,集中式版本控制系统发明了很多方法。有的采用编辑锁的形式(如VSS),更改文件前对文件锁定,其他人禁止对文件进行访问(甚至无法读取),完成修改并提交后,文件解锁。有的如SVN,允许多人同时编辑同一文件,但只有先进行提交的才能成功,后提交的会遇到“过时”错误,必须先获取版本库中的新增提交并和本地修改进行合并。即传统集中式版本控制系统,提交时必须和唯一的版本库所在的服务器保持连接,而且提交有可能会失败。 -对于像Git这样的分布式版本控制系统,提交总是会成功,这是因为提交并不涉及和\ -共享服务器的交互,是针对本地克隆版本库进行的本地操作。采用集中式的工作模式,\ -共享版本库作为各个用户各自本地版本库数据交换、沟通的中介,只有在本地克隆\ -版本库需要和共享版本库同步的时候才要和服务器建立连接。例如将本地所做的一个\ -或多个提交推送到共享服务器,或者将服务器上新的提交获取到本地克隆版本库。 +对于如Git这样的分布式版本控制系统,提交总是会成功,这是因为提交并不涉及和共享服务器的交互,是针对本地克隆版本库进行的本地操作。采用集中式的工作模式,共享版本库作为各个用户各自本地版本库数据交换、沟通的媒介,只有在本地克隆版本库需要和共享版本库同步的时候才要和服务器建立连接,例如将本地所做的一个或多个提交推送到共享服务器,或者将服务器上新的提交获取到本地克隆版本库。 -实际上无论采用分布式还是集中式的工作模式,Git都好像工作在一个独立的分支上\ -(克隆即分支),即使共享版本库和本地克隆版本库的分支名都叫做\ ``master``\ 。\ -如图4-20,三个用户克隆\ ``gitgithub/helloworld``\ 版本库后,各自在本地执行\ -了一次或多次提交。 +实际上无论采用分布式还是集中式的工作模式,Git都好像工作在一个独立的分支上(克隆即分支),即使共享版本库和本地克隆版本库的分支名都叫做 ``master`` 。如图4-20,三个用户克隆 ``gitgithub/helloworld`` 版本库后,各自在本地执行了一次或多册提交。 -.. figure:: /images/work-with-others/workflow-commit.png +.. figure:: /images/work-with-others/helloworld-commit.png :scale: 100 图4-20:在本地版本库中的提交 -三个用户各自的提交都会非常顺利,但是一旦决定将本地提交推送到共享服务器时就\ -可能遇到麻烦。用户 gotgithub 先执行推送,会非常顺利。如图4-21所示。 +三个用户各自的提交都会非常顺利,但是一旦决定将本地提交推送到共享服务器时就可能遇到麻烦。用户 gotgithub 先执行推送,会非常顺利。 :: gotgithub$ git push -.. figure:: /images/work-with-others/workflow-commit-push.png - :scale: 100 +而其他人就没有这么幸运了。Git的推送操作正如SVN等集中式版本控制系统的提交操作那样,先执行者成功,后执行者糟糕(要解决冲突,自动或手动)。 - 图4-21:用户gotgithub完成推送 +合并后推送 +--------------- -而其他人就没有这么幸运了,会报告错误:遇到非快进式推送。Git的推送操作就像SVN\ -等集中式版本控制系统的提交操作那样,先执行者成功,后执行者糟糕(要解决冲突,\ -自动或手动)。 +当用户gotgithub完成推送后,共享版本库以及三个用户的本地版本库如图4-21所示。其中共享版本库变得和gotgithub用户的本地版本库相一致。 -.. _merge-and-push: +.. figure:: /images/work-with-others/helloworld-push.png + :scale: 100 -合并后推送 ---------------- + 图4-21:用户gotgithub完成推送 -当用户gotgithub完成推送后,共享版本库以及三个用户的本地版本库如图4-21所示。\ -其中共享版本库变得和gotgithub用户的本地版本库相一致。此时如果用户supergirl\ -执行推送,会遇到错误:非快进式推送。 +此时如果用户ossxp-com执行推送,会遇到错误:非快进式推送。 :: - supergirl$ git push - To https://supergirl@github.com/gotgithub/helloworld.git + ossxp-com$ git push + To https://ossxp-com@github.com/gotgithub/helloworld.git ! [rejected] master -> master (non-fast-forward) - error: failed to push some refs to 'https://supergirl@github.com/gotgithub/helloworld.git' + error: failed to push some refs to 'https://ossxp-com@github.com/gotgithub/helloworld.git' To prevent you from losing history, non-fast-forward updates were rejected Merge the remote changes (e.g. 'git pull') before pushing again. See the 'Note about fast-forwards' section of 'git push --help' for details. -GitHub并不对强制推送进行限制,但是用户supergirl不要用\ ``git push -f``\ 命令\ -强制推送,因为那样会覆盖掉共享版本库中用户gotgithub的推送,正确的做法是获取\ -共享版本库中新提交,并在本地版本库中和本地提交合并。即执行: +GitHub并不对强制推送进行限制,但是用户ossxp-com不要用 ``git push -f`` 命令强制推送,因为那样会覆盖掉共享版本库中用户gotgithub的推送,正确的做法是获取共享版本库中新提交,并在本地版本库中和本地提交合并。过程如图4-22所示。 + +.. figure:: /images/work-with-others/helloworld-fetch-merge.png + :scale: 100 + + 图4-22:合并操作示意图 + +图4-22是一个分节动作,实际上用户ossxp-com只需执行一条命令,即完成所有的操作: :: - supergirl$ git fetch - supergirl$ git merge - -获取和合并操作过程如图4-22所示。 + ossxp-com$ git pull + +如果一切顺利,合并后共享版本库以及三个开发者各自本地版本库的示意图如图4-23所示。 -.. figure:: /images/work-with-others/workflow-fetch-merge.png +.. figure:: /images/work-with-others/helloworld-merged.png :scale: 100 - 图4-22:合并操作示意图 + 图4-23:用户ossxp-com完成合并的示意图 -实际上用户supergirl只需执行一条命令便可完成所有的操作: +但是合并操作并不总是会成功,如果自动合并失败,会在暂存区对合并前后文件进行标识,工作区进入冲突解决状态,在冲突解决完成之前不能提交。冲突解决Git支持和多种命令行及图形工具的整合,只需执行如下命令,即可调用已安装工具进行冲突解决。 :: - supergirl$ git pull + ossxp-com$ git mergetool + +冲突解决完毕,执行提交。 -即:\ ``git pull = git fetch + git merge``\ 。 +:: + + ossxp-com$ git commit -但是合并操作并不总是会成功,如果自动合并失败,会在暂存区对合并前后文件进行\ -标识,工作区进入冲突解决状态,在冲突解决完成之前不能提交。Git支持多种图形工具\ -帮助完成冲突解决,执行如下命令,即可自动调用已安装的冲突解决工具。 +如果在冲突解决过程把本地文件搞得一团糟,随时可以取消合并操作,让本地版本库的 ``master`` 分支退回到合并之前的状态,操作如下: :: - supergirl$ git mergetool + ossxp-com$ git reset --hard + +这时用户ossxp-com的本地版本库示意如图4-24所示。 + +.. figure:: /images/work-with-others/helloworld-merged-canceled.png + :scale: 100 + + 图4-24:取消合并后版本库示意图 + +取消合并操作后,分支 ``master`` 回退到合并之前,而分支 ``origin/master`` 则由于 ``git fetch`` 操作而变得和共享版本库当前 ``master`` 分支一样。若要再次开始合并操作,执行: -冲突解决完毕,执行提交即完成冲突解决。如果在冲突解决过程把本地文件搞得一团糟,\ -随时可以取消合并操作。执行命令\ ``git reset --hard``\ 会取消冲突的合并让\ -本地版本库回到合并之前的状态。 +:: -成功完成合并后将本地版本库中的提交推送到共享版本库: + ossxp-com$ git merge origin/master + +无论是自动合并还是手工合并,完成合并后的版本库示意图都如图4-23所示。用户ossxp-com若要将本地合并后的提交同步到共享服务器,还是执行推送操作。 :: - supergirl$ git push + ossxp-com$ git push -完成推送后的版本库示意图如图4-23所示。 +完成推送后的版本库示意图如图4-25所示。 -.. figure:: /images/work-with-others/workflow-merge-push.png +.. figure:: /images/work-with-others/helloworld-merged-pushed.png :scale: 100 - 图4-23:完成合并后推送 - -.. _rebase-and-push: + 图4-25:合并后推送 合并还是变基 --------------- -合并并非多个开发者的工作成果融合的唯一选择,有时甚至并非最佳选择。一方面合并\ -会产生除了合并双方(或多方)所有提交外的一个新提交,增加了代码审核的负担,\ -另一方面本地多个提交混杂一起与远程分支合并会更困难。在特定情况下,变基是合并\ -之外的另一个选择。 +合并会产生除了合并双方(或多方)所有提交外的一个新提交,这一方面会增加代码审核的负担,另一方面本地多个提交混杂一起与远程分支合并可能会比本地提交逐一迁移式合并更加困难。因此在特定情况下,变基是取代合并的一个选择。 -图4-24展示用户incredible采用合并和变基两种不同解决方案的操作结果。图中右上\ -是合并操作后的结果,右下是变基操作后的结果。 +图4-26展示用户jiangxin若采用合并和变基两种不同方案时本地版本库 ``master`` 分支的情况。图的左侧是合并,右侧是变基。 -.. figure:: /images/work-with-others/workflow-merge-or-rebase.png +.. figure:: /images/work-with-others/helloworld-merged-vs-rebase.png :scale: 100 - 图4-24:合并和变基结果比较 + 图4-26:合并和变基结果比较 -若用户 incredible 选择变基操作,执行命令如下: +用户jiangxin采用变基操作,执行命令如下: * 获取远程版本库的提交到本地的远程分支。 :: - incredible$ git fetch origin + jiangxin$ git fetch origin -* 执行变基操作,将本地\ ``master``\ 分支的提交变基到新的远程分支中。 +* 执行变基操作,将本地 ``master`` 分支的提交变基到新的远程分支中。 :: - incredible$ git rebase origin/master + jiangxin$ git rebase origin/master -如果一切顺利,变基后推送到共享版本库。 +如果一切顺利,变基后的本地版本库正如图4-26右侧示意的那样。向远程版本库推送,执行命令: :: - incredible$ git push + $ git push -推送后的版本库状态如图4-25所示。 - -.. figure:: /images/work-with-others/workflow-rebase-push.png - :scale: 100 - - 图4-25:变基后推送 - -如果希望在执行\ ``git pull``\ 时自动使用\ ``git rebase``\ 取代默认的\ -``git merge``\ 操作,可以在\ ``git pull``\ 命令行添加参数\ ``--rebase``\ 如下: - -:: - - $ git pull --rebase - -或者通过配置变量设置当前分支使用变基策略,即每次执行\ ``git pull``\ 命令时\ -对于\ ``master``\ 分支,采用变基操作取代默认的合并操作。 +如果希望在执行 ``git pull`` 时自动使用 ``git rebase`` 取代默认的 ``git merge`` 操作,可以进行如下设置: :: $ git config branch.master.rebase true -如果希望本地所有克隆版本库在执行\ ``git pull``\ 时都改变默认行为,将变基作为\ -首选,则如下设置全局变量。 +如果希望本地所有克隆版本库在执行 ``git pull`` 时都改变默认行为,将变基作为首选,则如下设置全局变量。 :: $ git config --global branch.autosetuprebase true + diff --git a/04-work-with-others/030-organization.rst b/04-work-with-others/030-organization.rst index 71235df..e81347b 100644 --- a/04-work-with-others/030-organization.rst +++ b/04-work-with-others/030-organization.rst @@ -1,181 +1,129 @@ -.. _organizations: - 组织和团队 =============== -GitHub 在早期没有专门为组织提供账号,很多企业用户或大型开源组织只好使用普通用户\ -账号作为组织的共享账号来使用。后来,GitHub推出了组织这一新的账号管理模式,满足大型\ -开发团队的需要。 - -* 组织账号是不能用来登录的,它包含一个Owner(拥有者)用户组,只有属于这个组的\ - 用户在登录后,才能切换为组织的管理者。 -* 可以创建任意多的团队(Team)即角色,对属于组织的用户进行管理。Owner Team\ - 就是组织中权限最高的角色。 -* 组织和用户一样可以创建项目,但是组织没有SSH公钥配置,也不能以组织的身份操作\ - 版本库。 -* 组织没有工作描述之类的个人账号才拥有的属性。 +GitHub最早没有专为组织而设的账号,很多企业用户或大的开源组织只好用普通用户账号作为组织的共享账号来使用。GitHub推出了组织这一新的账号管理模式,满足大的开发团队的需要。 -.. _new-org: +* 组织账号是不能登录的账号,包含一个Owner(拥有者)用户组,只有属于这个组的用户在登录后,才能切换为组织的管理者。 +* 可以创建任意多的团队(Team)即角色,对属于组织的用户进行管理。Owner Team就是组织中权限最高的角色。 +* 组织和用户一样可以创建项目,但是组织没有SSH公钥配置,即不能以组织的身份操作版本库。 +* 组织没有工作描述之类的个人才拥有的属性。 创建新组织 -------------- -组织是非登录账号,不能像创建普通登录账号那样直接创建,而是需要以GitHub用户\ -身份登录,然后再创建自己的组织,创建者成为组织天然的管理者。 +组织是非登录账号,不能像创建普通登录账号那样直接创建,而是需要以GitHub用户身份登录,然后再创建自己的组织,创建者成为组织天然的管理者。 -图4-26就是用户gotgithub登录后,通过点击右上角的账号设置图标进入账号设置界面,\ -然后再点击菜单中的“Organizations”进入组织管理界面。 +图4-27就是用户gotgithub登录后,通过“Account Settings”进入账号设置界面,再点击菜单中的“Organizations”进入组织管理界面。 .. figure:: /images/organization/new-org-1.png :scale: 100 - 图4-26:账号设置中的组织管理 + 图4-27:账号设置中的组织管理 -在初始的组织管理界面中组织列表为空,即尚不属于任何组织。可以选择把当前用户\ -gotgithub的账号转换为一个组织账号(前提是gotgithub的账号不属于任何组织)。\ -提供这一账号迁移功能是因为在GitHub提供组织这一新功能之前,很多公司或团队以\ -个人身份创建GitHub账号,但是以组织的形象出现,对于这类账号,GitHub提供了由\ -个人账号向组织账号迁移的途径。 +初始的组织管理界面中组织列表为空,即尚不属于任何组织。可以选择把当前用户gotgithub的账号转换为一个组织账号(前提是gotgithub的账号不属于任何组织)。提供这一账号迁移功能是因为在GitHub提供组织这一新功能之前,很多公司或团队以个人身份创建GitHub账号,但是以组织的形象出现,对于这类账号,GitHub提供了由个人账号向组织账号迁移的途径。在这里我们不进行这一迁移,而是以用户gotgithub的身份创建一个新的组织。 -在这里我们不进行这一迁移,而是以用户gotgithub的身份创建一个新的组织。点击\ -“Create New Organization”按钮,显示创建组织表单,如图4-27所示。 +点击“Create New Organization”按钮,显示创建组织表单,如图4-28所示。 .. figure:: /images/organization/new-org-2.png :scale: 100 - 图4-27:创建新组织 + 图4-28:创建新组织 -这里填写组织名为 GotGitOrg。创建组织还要选择一个付费方案,默认会选择免费的\ -没有私有版本库的开源方案。 +这里填写组织名为 GotGitOrg。创建组织还要选择一个付费方案,默认会选择免费的没有私有版本库的开源方案。 -接下来为新建组织设定拥有者(Owner),如图4-28所示。当前用户,即正在创建组织\ -的用户,理所当然成为组织拥有者之一。还可以为组织指派更多的组织拥有者,多个组织\ -拥有者的权限并无差别,都可以管理组织,甚至可以将其他用户从拥有者团队中删除。 +接下来为新建组织设定拥有者(Owner),如图4-29所示。当前用户,即正在创建组织的用户,理所当然成为组织拥有者之一。还可以为组织指派更多的组织拥有者,多个组织拥有者的权限并无差别,都可以管理组织,甚至可以将其他用户从拥有者团队中删除。 .. figure:: /images/organization/new-org-3.png :scale: 100 - 图4-28:指派组织拥有者 + 图4-29:指派组织拥有者 -完成创建后,访问用户账号设置界面中的组织面板,如图4-29所示,列出当前用户所属\ -的组织(GotGitOrg)。可以重新对组织进行设定,或者退出组织。注意因为当前用户\ -已经属于一个以上的组织,所以右侧将当前用户转换为组织的按钮被置灰。 +完成创建后,在组织管理面板中(如图4-30)列出当前用户所属的组织,可以重新对组织进行设定,或者退出组织。注意因为当前用户已经属于一个以上的组织,所以右侧将当前用户转换为组织的按钮被置灰。 .. figure:: /images/organization/new-org-4.png :scale: 100 - 图4-29:加入组织后的组织管理界面 - -.. _org-settings: + 图4-30:加入组织后的组织管理界面 组织管理 ------------------ -当用户gotgithub成为新建组织GotGitOrg的一员后,就可以在用户和组织的界面之间切换。\ -点击页面左上角“github”文字图标进入仪表板界面。 +当用户gotgithub成为新建组织GotGitOrg的一员后,就可以在用户和组织的界面之间切换。图4-31显示用户gotgithub的仪表板界面。 .. figure:: /images/organization/dashboard-header.png :scale: 100 - 图4-30:用户仪表板界面 + 图4-31:用户仪表板界面 -仪表板页面左上角“github”文字图标的下面就是用户上下文列表框。点击用户上下文\ -下拉列表,如图4-31所示。 +在仪表板页面点击用户下拉框,显示如图4-32的用户上下文下拉列表。 .. figure:: /images/organization/dashborad-context.png :scale: 100 - 图4-31:用户上下文切换列表 + 图4-32:用户上下文切换列表 -在用户上下文列表中选择组织GotGitOrg作为用户上下文后,则仪表板中显示的菜单和\ -个人账号仪表板菜单略有不同,如图4-32所示。 +在用户上下文列表中选择组织GotGitOrg作为用户上下文后,则仪表板显示与组织GotGitOrg有关信息,如图4-33所示。 .. figure:: /images/organization/org-dashboard.png :scale: 100 - 图4-32:组织GotGitOrg的仪表板界面 + 图4-33:组织GotGitOrg的仪表板界面 -组织的仪表板界面与用户仪表板的不同之处在于增加了团队管理(Team)和组织管理\ -(Organization Settings)。选择菜单中的“Team”进入团队管理界面,可以在组织中\ -添加任意数量的团队。添加新团队的界面如图4-33所示。 +组织的仪表板界面与用户仪表板的不同之处在于增加了团队管理(Team)和组织管理(Organization Settings)。选择菜单中的“Team”进入团队管理界面,可以在组织中添加任意数量的团队。添加新团队的界面如图4-34所示。 .. figure:: /images/organization/new-team.png :scale: 100 - 图4-33:添加新团队iOS-Team + 图4-34:添加新团队iOS-Team -创建一个团队需要提供四个选项(如图4-33): +创建一个团队需要提供四个选项(如图4-34): 1. 团队名称。如:iOS-Team。 -2. 团队成员。如:supergirl和omnidroid两个用户作为团队成员。 -3. 团队权限。有三个选择:只读(Pull Only)、读写(Push & Pull)、读写并管理\ - (Push, Pull & Administrative)。 +2. 团队成员。如:jiangxin和ossxp-com两个用户作为团队成员。 +3. 团队权限。有三个选择:只读(Pull Only)、读写(Push & Pull)、读写并管理(Push, Pull & Administrative)。 4. 授权版本库。可以添加一个或多个版本库,只有对授权的版本库才拥有指定权限。 -其中团队授权中的只读授权对于免费组织账号创建的开源项目没有实际意义,因为开源\ -项目人人可读,只有对于付费的组织账号创建的私密版本库才体现出价值。关于付费账号\ -和私密版本库将在后面的章节介绍。接下来介绍如何在组织账号下创建版本库。 - -.. _org-repo-mgmt: +其中团队授权中的只读授权对于免费组织账号创建的开源项目没有实际意义,因为开源项目人人可读,只有对于付费的组织账号创建的私密版本库才体现出价值。关于付费账号和私密版本库将在后面的章节介绍。本例为新增团队添加了版本库 ``GotGitOrg/OrgRepo1`` ,这个版本库是如何建立的呢?下面就介绍如何为组织创建版本库。 版本库管理 -------------------- -组织拥有独立的项目托管空间,点击页面左上角的“github”文字图标进入组织账号的\ -仪表板界面。刚刚建立的组织账号的版本库尚未创建,点击图4-32所示的“New Repository”\ -按钮,创建版本库(即项目)。 - -新建版本库的界面如图4-34所示。 +组织拥有独立的项目托管空间,刚刚建立的组织账号的版本库尚未创建,点击图4-33中的“New Repository”按钮,创建版本库(即项目)。新建版本库的界面如图4-35所示。 .. figure:: /images/organization/new-prj-for-org.png :scale: 100 - 图4-34:新建项目界面 + 图4-35:新建项目界面 -在组织的托管空间创建项目与在普通用户的空间下创建稍有不同,增加了团队设置\ -下拉框。图4-34显示在创建名为MyiPad项目时,只能为项目指派一个已定义团队,\ -要想为项目指派更多团队可以在项目创建完毕通过项目管理界面添加。 +在组织的托管空间创建项目与在普通用户的空间下创建稍有不同,增加了团队设置下拉框。图4-35显示在创建名为MyiPad项目时,只能为项目指派一个已定义团队,要想为项目指派更多团队可以在项目创建完毕通过项目管理界面添加。 -下面来看一看如何为已建立项目指派更多的团队。进入项目管理页面,点击左侧菜单项\ -“Team”显示项目的团队管理界面,可以通过该界面,为项目添加和移除团队,如图4-35所示。 +下面来看一看如何为已建立项目指派更多的团队。进入项目管理页面,点击左侧菜单项“Team”显示项目的团队管理界面,可以通过该界面,为项目添加和移除团队,如图4-36所示。 .. figure:: /images/organization/org-prj-admin-teams.png :scale: 100 - 图4-35:项目的团队管理 + 图4-36:项目的团队管理 -属于团队的项目(版本库)可以转移给个人,反之亦然。图4-36展示了如何通过项目\ -管理界面在用户和组织之间转移项目(版本库)。 +归属团队的项目(版本库)可以转移给个人,反之毅然。图4-37展示了如何通过项目管理界面在用户和组织之间转移项目(版本库)。 .. figure:: /images/organization/org-prj-admin-transfer.png :scale: 100 - 图4-36:项目转移 - -.. _pros-of-org: + 图4-37:项目转移 个人还是组织 ---------------------- -若使用“Fork + Pull”的工作模式,通过个人账号还是组织账号托管版本库,几乎没有\ -什么差别。如果一定要找出点不同,那就是在向托管版本库提交Pull Request时,邮件\ -通知的用户范围有所不同。 +若使用“Fork + Pull”的工作模式,通过个人账号还是组织账号托管版本库,几乎没有什么差别。如果一定要找出点不同,那就是在向托管版本库提交Pull Request时,邮件通知的用户范围有所不同。 + +* 对于个人账号,对其托管空间内的版本库发出Pull Request,通知邮件会发送给该个人账号及该版本库设置的所有协作者(如果有的话)的邮箱。 +* 对于组织,对其托管空间内的版本库发出Pull Request,不会向组织的邮箱发送Pull Request,也不会向组织的所有者(Owner团队)发送通知邮件,而是向在版本库中拥有Push权限的团队(非Owner团队)成员发送通知邮件。 -* 对于个人账号,对其托管空间内的版本库发出Pull Request,通知邮件会发送给该\ - 个人账号及该版本库设置的所有协作者(如果有的话)的邮箱。 -* 对于组织,对其托管空间内的版本库发出Pull Request,不会向组织的邮箱发送\ - Pull Request,也不会向组织的所有者(Owner团队)发送通知邮件,而是向在版本库中\ - 拥有Push权限的团队(非Owner团队)成员发送通知邮件。 +因此,如果在组织的托管空间创建版本库,一定要要为版本库指派一个拥有Push权限的团队,以免以“Fork + Pull”模式工作时,Pull Request没有人响应。 -因此,如果在组织的托管空间创建版本库,一定要要为版本库指派一个拥有Push权限的\ -团队,以免以“Fork + Pull”模式工作时,Pull Request没有人响应。 +若是以共享版本库方式(即集中式协同模式)工作的话,使用组织来托管版本库会比使用个人账号托管有效率得多。 -若是以共享版本库方式(即集中式协同模式)工作的话,使用组织来托管版本库会比\ -使用个人账号托管有效率得多。 +* 以个人账号托管,需要逐一为版本库设置协作者(Collaborators),如果版本库较多且授权相同,配置过程繁琐且易出错。 +* 以组织方式托管,将用户分组,划分为一个一个的团队(Team),以团队为单位授权则方便得多。 +* 如果是以付费账号创建的私密版本库,使用组织方式管理,会有包括只读、读写等更丰富的授权类型,更符合项目管理的实际。 -* 以个人账号托管,需要逐一为版本库设置协作者(Collaborators),如果版本库较多\ - 且授权相同,配置过程繁琐且易出错。 -* 以组织方式托管,将用户分组,划分为一个一个的团队(Team),以团队为单位授权\ - 则方便得多。 -* 如果是以付费账号创建的私密版本库,使用组织方式管理,会有包括只读、读写等\ - 更丰富的授权类型,更符合项目管理的实际。 diff --git a/04-work-with-others/040-code-review.rst b/04-work-with-others/040-code-review.rst index 73326d3..ba22f5b 100644 --- a/04-work-with-others/040-code-review.rst +++ b/04-work-with-others/040-code-review.rst @@ -1,102 +1,75 @@ -.. _code-comments: - -代码评注 +代码评审 ============ -针对项目的每一次Pull Request就相当于一次代码评审,评审以讨论的形式显示在\ -Pull Request中。 - -在Pull Request中还能够看到对应的提交(一个或多个),并可以直接针对提交进行\ -代码评注。对于采用集中式协同的项目,即使较少使用 Pull Request,也同样可以\ -使用代码评注。代码评注会触发通知邮件给项目的开发者。 +针对项目的每一次Pull Request就相当于一次代码评审,评审以讨论的形式显示在Pull Request中。在Pull Request中还看到对应的提交(一个或多个),可以直接针对提交进行代码评注。对于采用集中式协同的项目,虽然很少用到Pull Request,但同样也可以使用代码评注。代码评注会触发通知邮件给项目的开发者。 -代码评注有两种形式,一种是针对整个提交的评注,另外一种是对代码进行逐行评注。 - -.. _commit-comments: +代码评注有两种形式,一种是针对整个提交的评注,另外一种是对代码的逐行评注。 提交评注 ------------ -查看项目的提交历史,从中选择一个提交,如图4-37所示。 +透过项目的提交历史,可以看到所选分支所有的历史提交,如图4-38所示。选择其中一个提交。 .. figure:: /images/work-with-others/commit-history.png :scale: 100 - 图4-37:helloworld项目提交历史 + 图4-38:gotgit项目提交历史 -如图4-38是查看提交的界面。除了提交说明、提交者信息之外,还显示提交所修改的\ -文件和改动差异。在查看提交页面的最下方显示一个提交评注对话框,可以在其中写下\ -评注。评注可以使用 Markdown 语法。 +在查看提交的界面,除了提交日志、提交者信息之外,还显示提交所修改的文件和改动差异。在查看提交页面的最下方显示一个提交评注对话框,如图4-39所示。 .. figure:: /images/work-with-others/commit-note.png :scale: 100 - 图4-38:添加提交评注 + 图4-39:添加提交评注 -添加评注后,所评注的提交的作者会收到通知邮件,提醒针对自己的提交有了新的评论。\ -通知邮件如图4-39所示。 +添加评注的同时会向项目中开发者发送一封通知邮件,提醒针对项目的某个提交有了新的评论。通知邮件如图4-40所示。 .. figure:: /images/work-with-others/commit-note-email-notify.png :scale: 100 - 图4-39:提交评注的通知邮件 + 图4-40:提交评注的通知邮件 -通过Web界面可以看到添加在提交下方的评注,并可以撰写新的评注展开讨论。评注者\ -本人或提交的作者还可以编辑甚至删除评注。如图4-40所示。 +通过Web界面可以看到添加在提交下方的评注。评注者和项目的开发者还可以编辑和删除评注。如图4-41所示。 .. figure:: /images/work-with-others/commit-note-admin.png :scale: 100 - 图4-40:提交评注 + 图4-41:提交评注 -GitHub还支持Git自身提供的评注功能\ [#]_\ ,如图4-41所示的是提交\ -http://git.io/git-notes\ [#]_\ 的评注,这个评注并非通过GitHub添加的,而是由\ -``git-note``\ 命令提交的评注。这种评注针对一个特定提交只能有一个,GitHub只能\ -显示不能编辑和删除。关于如何通过命令行查看\ ``git-note``\ 格式的评注,参见\ -《Git权威指南》第570页“41.5 Git评注”。 +GitHub还支持Git自身提供的评注功能 [#]_ ,如图4-42所示的是提交 http://goo.gl/ujw5e [#]_ 的评注,这个评注并非通过GitHub添加的,而是由 ``git-note`` 命令提交的评注。这种评注针对一个特定提交只能有一个,GitHub只能显示不能编辑和删除。关于如何通过命令行查看 ``git-note`` 格式的评注,参见《Git权威指南》第570页“41.5 Git评注”。 .. figure:: /images/work-with-others/commit-note-by-git-note.png :scale: 100 - 图4-41:git-note评注 + 图4-42:git-note评注 -.. _line-comments: 逐行评注 ------------ -还是以\ ``gotgithub/helloworld``\ 版本库中的提交为例,看一下GitHub支持的逐行\ -评注功能,即针对提交中的任意一行添加评注。浏览提交,如图4-42所示,当鼠标置于\ -任意一行代码时,在该行代码的左侧会显示一个添加注释的图标。 +还是以 ``gotgit/gotgit`` 版本库中的提交为例,看一下GitHub支持的逐行评注功能,即针对提交中的任意一行添加评注。浏览提交,如图4-43所示,当鼠标至于任意一行代码时,在该行代码的左侧会显示一个添加注释的图标。 .. figure:: /images/work-with-others/commit-line-note-btn.png :scale: 100 - 图4-42:添加逐行评注按钮 + 图4-43:添加逐行评注按钮 -点击该图标(用于添加逐行评注的图标),会显示如图4-43所示的添加逐行评注对话框。\ -该评注对话框出现在两行代码之间,在其中写下评注。 +点击该图标(用于添加逐行评注的图标),会显示如图4-44所示的添加逐行评注对话框。该评注对话框出现在两行代码之间,在其中写下评注。 .. figure:: /images/work-with-others/commit-line-note-form.png :scale: 100 - 图4-43:添加逐行评注 + 图4-44:添加逐行评注 -添加评注后,项目的开发人员同样会收到邮件通知。针对同一行代码的多次评论按时间\ -顺序依次显示,图4-44展示了多个行间评注,其中一个评注还使用 Markdown 语法嵌入了\ -一个图片。 +添加评注后,项目的开发人员同样会收到邮件通知。图4-45是添加了逐行评注后的提交,在提交的最下方还可以看到之前针对整个提交的评注。 .. figure:: /images/work-with-others/commit-line-note.png :scale: 100 - 图4-44:逐行评注和提交评注 - -更有意思的评注可以围观\ ``MrMEEE/bumblebee``\ 项目的一个bug修正提交(被戏称\ -一个空格引发的惨案)。地址: http://git.io/giant-bug\ [#]_\ 。 + 图4-45:逐行评注和提交评注 ---- .. [#] http://www.kernel.org/pub/software/scm/git/docs/git-notes.html -.. [#] 即网址 https://github.com/ossxp-com/gitdemo-commit-tree/commit/e80aa74 -.. [#] 即网址 https://github.com/MrMEEE/bumblebee/commit/a047be85247755cdbe0acce6 +.. [#] 实际地址为 https://github.com/ossxp-com/gitdemo-commit-tree/commit/e80aa7481beda65ae00e35afc4bc4b171f9b0ebf diff --git a/04-work-with-others/050-issue.rst b/04-work-with-others/050-issue.rst index 422792c..97cbced 100644 --- a/04-work-with-others/050-issue.rst +++ b/04-work-with-others/050-issue.rst @@ -1,159 +1,117 @@ -.. _issues: - 缺陷跟踪 =============== -缺陷跟踪(Bug Tracking)是软件研发流程中重要的一环,集项目需求管理和缺陷管理\ -于一身,通过对研发工作流的控制帮助团队建立规范的研发体系。GitHub提供轻量级的\ -缺陷跟踪模块,称为Issues。小巧、易用的Issues模块能与Pull Request紧密整合,\ -是Pull Request工作流的有益补充。 +缺陷跟踪(Bug Tracking)是软件研发流程中重要的一环,集项目需求管理和缺陷管理于一身,通过对研发工作流的控制帮助团队建立规范的研发体系。 -一个小型、管理文档和网页的项目,使用Pull Request往往就足够了。试想如果贡献者\ -能够直接修改代码(Fork and edit this file)并通过Pull Request贡献给项目核心\ -开发者,那么为什么还要通过Issues模块报告错误并由他人来更改呢?但是对于大型\ -项目需要做需求管理,或者参与代码开发有难度,则非常有必要通过Issues模块启用\ -缺陷跟踪系统,提供更多途径让贡献者参与到项目中来。 +GitHub提供轻量级的缺陷跟踪模块,称为Issues。小巧、易用的Issues模块能与Pull Request紧密整合,是Pull Request工作流的有益补充。一个小型、管理文档和网页的项目,使用Pull Request往往就足够了。试想如果贡献者能够直接修改代码(Fork and edit this file)并通过Pull Request贡献给项目核心开发者,那么为什么还要通过Issues模块报告错误并由他人来更改呢?但是对于大型项目需要做需求管理,或者参与代码开发有难度,则非常有必要通过Issues模块启用缺陷跟踪系统,提供更多途径让贡献者参与到项目中来。 -缺陷跟踪可以通过项目的管理页面开启或关闭,如图4-45所示。 +缺陷跟踪可以通过项目的管理页面开启或关闭,如图4-46所示。 -.. figure:: /images/issues/project-admin-features-issue.png +.. figure:: /images/work-with-others/project-admin-features-issue.png :scale: 100 - 图4-45:开启或关闭Issues模块 - -.. _labels: + 图4-46:开启或关闭Issues模块 标签 -------- -缺陷跟踪系统通常可用于管理多种不同类型的问题:需求、缺陷或其它,也可以通过\ -项目不同模块、组件来为问题分类。GitHub在问题分类的实现上非常简单,通过标签\ -(label)来为问题建立分类。 +缺陷跟踪系统通常可用于管理多种不同类型的问题:需求、缺陷或其它,也可以通过项目不同模块、组件来为问题分类。GitHub在问题分类的实现上非常简单,通过标签(label)来为问题建立分类。 -开启Issues模块后,项目的菜单中多出一个“Issues”项,点击则进入问题浏览界面,\ -如图4-46所示。左侧的边栏是问题过滤器,由上至下分为三个部分。最上面的过滤器\ -根据问题的所有者对问题进行筛选,默认选择所有人的问题。中间的过滤器是根据\ -里程碑对问题进行筛选,默认未选定任何里程碑(初始尚未创建任何里程碑),不对\ -问题进行里程碑过滤。最下面的过滤器依据问题标签对问题进行筛选,初始标签尚未\ -创建。 +开启Issues模块后,项目的菜单中多出一个“Issues”项,点击则进入问题浏览界面,如图4-47所示。左侧的边栏是问题过滤器,由上至下分为三个部分。最上面的过滤器根据问题的所有者对问题进行筛选,默认选择所有人的问题。中间的过滤器是根据里程碑对问题进行筛选,默认未选定任何里程碑(初始也未创建任何里程碑),不对问题进行里程碑过滤。最下面的过滤器依据问题标签对问题进行筛选,初始标签尚未创建。 -.. figure:: /images/issues/issue-no-label.png +.. figure:: /images/work-with-others/issue-no-label.png :scale: 100 - 图4-46:尚未定义标签 + 图4-47:尚未定义标签 -鼠标点击左侧边栏标签过滤器中的新建标签的文本框,显示如图4-47所示的新建标签\ -界面。输入新的标签名,并为标签选择一个颜色,创建新的标签。 +鼠标点击左侧边栏标签过滤器中的新建标签的文本框,显示如图4-48所示的新建标签界面。输入新的标签名,并为标签选择一个颜色,创建新的标签。 -.. figure:: /images/issues/issue-new-label.png +.. figure:: /images/work-with-others/issue-new-label.png :scale: 100 - 图4-47:创建新标签 + 图4-48:创建新标签 -创建的标签显示在过滤器中,如图4-48所示。点击过滤器中的标签则对问题进行筛选,\ -取消过滤器可以点击图中标记的“Clear active milestone and label filters”链接。 +创建的标签显示在过滤器中,如图4-49所示。点击过滤器中的标签则对问题进行筛选,取消过滤器可以点击图中标记的“Clear active milestone and label filters”链接。 -.. figure:: /images/issues/issue-labels.png +.. figure:: /images/work-with-others/issue-labels.png :scale: 100 - 图4-48:过滤器中的标签选项 + 图4-49:过滤器中的标签选项 标签过滤器下方的“Manage Labels”按钮用于管理标签,下面的输入框用于创建新的标签。 -.. _milestone: - 里程碑 ----------- -里程碑(Milestones)是项目进度管理的重要工具。在传统项目管理中,里程碑对应\ -于一个项目开发计划、一个软件版本;在敏捷项目管理中,里程碑对应于一个Sprint\ -(冲刺);在软件代码的版本库中则对应于一个标签(tag)或分支(branch)。 +里程碑(Milestones)是项目进度管理重要工具。在传统项目管理中,里程碑对应于一个项目开发计划、一个软件版本;在敏捷项目管理中,里程碑对应于一个Sprint(冲刺);在软件代码的版本库中则对应于一个标签(tag)或分支(branch)。 -在Issues模块中的“Milestones”页面用于里程碑管理。创建新的里程碑需要输入里程碑\ -名称和里程碑的截止时间,如图4-49所示。 +在Issues模块中的“Milestones”页面用于里程碑管理。创建新的里程碑需要输入里程碑名称和里程碑的截止时间,如图4-50所示。 -.. figure:: /images/issues/issue-new-milestone.png +.. figure:: /images/work-with-others/issue-new-milestone.png :scale: 100 - 图4-49:创建新里程碑 + 图4-50:创建新里程碑 -创建的里程碑以进度条形式显示在里程碑页面中,如图4-50所示定义了两个里程碑。\ -这两个里程碑的时间跨度定义的太长,敏捷的项目管理从来不这么定义。 +创建好的里程碑以进度条形式显示在里程碑页面中,如图4-51所示定义了两个里程碑。这两个里程碑的时间跨度定义的太长,敏捷的项目管理从来不这么定义。 -.. figure:: /images/issues/issue-milestones.png +.. figure:: /images/work-with-others/issue-milestones.png :scale: 100 - 图4-50:里程碑列表 + 图4-51:里程碑列表 -.. _lifecycle: Issue的生命周期 ----------------- -GitHub的Issues模块非常简单,对标签和里程碑进行简单的设置后,基本上就完成了\ -Issues模块的配置工作,接下来就是如何创建和修改Issue,完成项目的缺陷跟踪和\ -需求管理等,这才是Issues模块的主要工作。 +GitHub的Issues模块非常简单,对标签和里程碑进行简单的设置后,基本上就完成了Issues模块的配置工作,接下来就是如何创建和修改Issue,完成项目的缺陷跟踪和需求管理等,这才是Issues模块的主要工作。 -每个Issue都有自己的生命周期,从问题的创建,到问题的指派,再到问题的解决,\ -直至问题的关闭。图4-51就是以普通贡献者身份为项目创建Issue。 +每个Issue都自己的生命周期,从问题的创建,到问题的指派,再到问题的解决,直至问题的关闭。图4-52就是普通贡献者身份为项目创建Issue。 -.. figure:: /images/issues/issue-new-by-non-member.png +.. figure:: /images/work-with-others/issue-new-by-non-member.png :scale: 100 - 图4-51:以普通贡献者身份创建问题 + 图4-52:贡献者创建问题 -录入问题标题和描述后,点击“Submit new issue”按钮,完成问题创建。图4-52显示了\ -新建立的问题,可以看出新建问题尚未设置标签。 +录入问题标题和描述后,点击“Submit new issue”按钮,完成问题创建。图4-53显示了新建立的问题,可以看出新建问题尚未设置标签。 -.. figure:: /images/issues/issue-created.png +.. figure:: /images/work-with-others/issue-created.png :scale: 100 - 图4-52:新创建的问题尚未添加标签等 + 图4-53:新创建的问题尚未添加标签等 -普通贡献者创建问题时只能录入问题的标题和描述,而不能设置问题的指派\ -(谁来负责)、添加标签和设置里程碑。如果希望问题通知到特定的开发者,\ -可以在问题描述中以“@用户名”的方式通知到该用户\ [#]_\ ,这也是众多社交\ -软件通行的做法。 +普通贡献者创建问题时只能录入问题的标题和描述,而不能设置问题的指派(谁来负责)、添加标签和设置里程碑。如果希望问题通知到特定的开发者,可以在问题描述中以“@用户名”的方式通知到该用户 [#]_ ,这也是众多社交软件通行的做法。 -项目成员创建问题时,拥有更大权限,也有更多的可选项。如图4-53所示。 +项目成员创建问题时,拥有更大权限,也有更多的可选项。如图4-54所示。 -.. figure:: /images/issues/issue-new-by-member.png +.. figure:: /images/work-with-others/issue-new-by-member.png :scale: 100 - 图4-53:以项目成员身份创建问题 + 图4-54:项目成员创建问题有更多权限 -完成上述两个问题的创建后,问题浏览界面显示新创建的两个问题,一个以项目成员\ -身份创建的问题已经被设置了“缺陷”的标签,而另外一个问题则没有设置任何标签。\ -如图4-54所示。 +完成上述两个问题的创建后,问题浏览界面显示出新创建的两个问题,一个以项目成员身份创建的问题已经被设置了“缺陷”的标签,而另外一个问题则没有设置任何标签。如图4-55所示。 -.. figure:: /images/issues/issue-list.png +.. figure:: /images/work-with-others/issue-list.png :scale: 100 - 图4-54:所有问题列表 + 图4-55:所有问题列表 -以项目成员身份登录,在问题浏览界面即可为问题重新设定标签,指派负责人,设置\ -里程碑,以及关闭问题等。如图4-55所示。 +以项目成员身份登录,在问题浏览界面即可为问题重新设定标签,指派负责人,设置里程碑,以及关闭问题等。如图4-56所示。 -.. figure:: /images/issues/issue-update.png +.. figure:: /images/work-with-others/issue-update.png :scale: 100 - 图4-55:为问题添加指派、里程碑和标签 + 图4-56:为问题添加指派、里程碑和标签 -在问题浏览页面的过滤器中选择里程碑”Version 4.0“,可以看到两条问题都显示出来,\ -这是因为这两条问题都属于该里程碑。里程碑的进度条显示进度为零,这是因为里程碑\ -所包含的全部(两个)问题都处于打开状态,尚未解决。如图4-56所示。 +在问题浏览页面的过滤器中选择里程碑”Version4.0“,可以看到两条问题都显示出来,这是因为这两条问题都属于该里程碑。里程碑的进度条显示进度为零,这是因为里程碑所包含的全部(两个)问题都处于打开状态,尚未解决。如图4-57所示。 -.. figure:: /images/issues/issue-list-with-milestone.png +.. figure:: /images/work-with-others/issue-list-with-milestone.png :scale: 100 - 图4-56:通过里程碑筛选问题 + 图4-57:通过里程碑筛选问题 -邮件通知功能是缺陷跟踪系统推动工作流的重要工具,GitHub的Issues模块也具有邮件\ -通知功能。除了像其他缺陷跟踪系统在收到邮件通知后,访问Web界面参与问题的讨论外,\ -还可以直接以邮件回复的功能参与到工作流中\ [#]_\ 。 +邮件通知功能是缺陷跟踪系统推动工作流的重要工具,GitHub的Issues模块也具有邮件通知功能。除了像其他缺陷跟踪系统在收到邮件通知后,访问Web界面参与问题的讨论外,还可以直接以邮件回复的功能参与到工作流中 [#]_ 。 -GitHub还支持版本库提交和问题建立关联,只要提交说明中出现“#xxx”(Issue编号)\ -字样。如果在提交说明中的问题编号前出现特定关键字,还可以关闭问题。支持的关键字有: +GitHub还支持版本库提交和问题建立关联,只要提交说明中出现“#xxx”(Issue编号)字样。如果在提交说明中的问题编号前出现特定关键字,还可以关闭问题。支持的关键字有: * fixes #xxx * fixed #xxx @@ -162,7 +120,7 @@ GitHub还支持版本库提交和问题建立关联,只要提交说明中出 * close #xxx * closed #xxx -下面就以\ ``gotgithub/helloworld``\ 版本库为例,关闭编号为“#1”的问题。 +下面就以 ``gotgithub/helloworld`` 版本库为例,关闭编号为“#1”的问题。 * 克隆版本库,若本地工作区尚不存在。 @@ -170,39 +128,19 @@ GitHub还支持版本库提交和问题建立关联,只要提交说明中出 $ git clone git@github.com:gotgithub/helloworld.git $ cd helloworld - -* 编辑文件\ `src/main.c`\ ,改正“问题#1”发现的文字错误。 - - :: - - $ vi src/main.c - $ git diff - diff --git a/src/main.c b/src/main.c - index 3daf9fe..f974b49 100644 - --- a/src/main.c - +++ b/src/main.c - @@ -19,7 +19,7 @@ int usage(int code) - " say hello to the world.\n\n" - " hello -v, --version\n" - " show version.\n\n" - - " hello -h, -help\n" - + " hello -h, --help\n" - " this help screen.\n\n"), _VERSION); - return code; - } - - -* 将修改添加至暂存区。 + +* 在工作区中进行修改、添加文件等,然后添加至暂存区。 :: - $ git add -u + hack, hack, hack... + $ git add -i -* 提交,并在提交说明中用\ ``fixed #xxx``\ 关键字关闭相关问题。 +* 提交说明中用 ``fixed #xxx`` 关键字关闭相关问题。 :: - $ git commit -m "Fixed #1: -help should be --help." + $ git commit -m "Fixed #1: Source code for Hello world." * 向GitHub版本库推送。 @@ -210,129 +148,104 @@ GitHub还支持版本库提交和问题建立关联,只要提交说明中出 $ git push -推送完毕后,在问题浏览界面可以看到里程碑“Version 4.0”的进度已经完成了一半,\ -即其中一个问题(#1)已经完成并关闭。如图4-57所示。 +推送完毕后,在问题浏览界面可以看到里程碑“Version4.0”的进度已经完成了一半,即其中一个问题(#1)已经完成并关闭。如图4-58所示。 -.. figure:: /images/issues/issue-milestone-half-closed.png +.. figure:: /images/work-with-others/issue-milestone-half-closed.png :scale: 100 - 图4-57:关闭一个问题,里程碑完成50% + 图4-58:关闭一个问题,里程碑完成50% -查看已经完成的问题(#1),可以看到其中关联到一个提交,该提交正是我们刚刚创建的。\ -如图4-58所示。 +查看已经完成的问题(#1),可以看到其中关联到一个提交,该提交正是我们刚刚创建的。如图4-59所示。 -.. figure:: /images/issues/issue-closed-by-commit.png +.. figure:: /images/work-with-others/issue-closed-by-commit.png :scale: 100 - 图4-58:已关闭问题中的提交链接 + 图4-59:已关闭问题中的提交链接 -点击关联的提交,显示如图4-59的提交界面,出现在提交说明中的问题编号也可点击,\ -指向缺陷追踪系统中该问题的链接。 +点击关联的提交,显示如图4-60的提交界面,出现在提交说明中的问题编号也可点击,指向缺陷追踪系统中该问题的链接。 -.. figure:: /images/issues/commit-link-to-issue.png +.. figure:: /images/work-with-others/commit-link-to-issue.png :scale: 100 - 图4-59:提交中的问题链接 - -.. _pull-request-as-issue: + 图4-60:提交中的问题链接 Pull Requst也是Issue -------------------------- -Pull Request和Issue一样,也是一种对项目的反馈,而且是更为主动的反馈。GitHub的\ -Issues模块将Pull Request也纳入到问题的管理之中,完美地将Pull Request整合到问题\ -追踪的框架之中。 +Pull Request和Issue一样,也是一种对项目的反馈,而且是更为主动的反馈。GitHub的Issues模块将Pull Request也纳入到问题的管理之中,完美地将Pull Request整合到问题追踪的框架之中。 -为了弄清二者之间的关联,首先创建一个Pull Request。 +为了弄清二者之间的关联,首先创建一个Pull Request。以非项目成员(用户 wangsheng [#]_ )的账号访问 ``gotgithub/helloworld`` 项目,查看文件 ``README.mkd`` ,点击“Fork and edit this file”按钮快速创建项目分支,如图4-61所示。 -以非项目成员(如用户 omnidroid)的账号访问\ ``gotgithub/helloworld``\ 项目,\ -查看文件\ ``src/Makefile``\ ,点击“Fork and edit this file”按钮快速创建派生\ -项目,如图4-60所示。 - -.. figure:: /images/issues/fork-and-edit-btn-for-issue.png +.. figure:: /images/work-with-others/fork-and-edit-btn-for-issue.png :scale: 100 - 图4-60:在线编辑并创建派生项目 + 图4-61:在线编辑并创建项目分支 -通过GitHub提供的在线编辑功能修改\ ``src/Makefile``\ 文件,修改完毕后撰写提交\ -说明,点击“Propose File Change”按钮提交。如图4-61所示。 +通过GitHub提供的在线编辑功能修改 ``README.mkd`` 文件,修改完毕后撰写提交说明,点击“Propose File Change”按钮提交。如图4-62所示。 -.. figure:: /images/issues/fork-and-edit-form-for-issue.png +.. figure:: /images/work-with-others/fork-and-edit-form-for-issue.png :scale: 100 - 图4-61:在线编辑并提交 - -在提交说明中特意使用了“Fixed #2”关键字,以便该提交被上游版本库接纳后能够关闭关联的问题。 + 图4-62:在线编辑并提交 -当完成提交后,GitHub会自动开启创建新的Pull Request对话框,如图4-62所示。 +留意在提交说明中使用了“Fixed #2”关键字,以便可以通过提交关闭相应的问题。当提交修改后,GitHub会自动开启创建新的Pull Request对话框,如图4-63所示。 -.. figure:: /images/issues/new-pull-request-for-issue.png +.. figure:: /images/work-with-others/new-pull-request-for-issue.png :scale: 100 - 图4-62:创建Pull Request + 图4-63:创建Pull Request -Pull Request创建完毕后,除了在菜单项“Pull Requests”中有显示外,在“Issues”的\ -问题浏览页面中也会显示。如图4-63所示,新建立的Pull Request的编号不是从壹开始\ -创建,而是接着问题的编号顺序创建,所以当Pull Request出现在问题列表中时,\ -如果不注意后面的山型的分支图标,根本意识不到这不是一个普通的问题(Issue),\ -而是一个Pull Request。 +Pull Request创建完毕后,除了在菜单项“Pull Requests”中有显示外,在“Issues”的问题浏览页面中也会显示。如图4-64所示,新建立的Pull Request的编号不是从壹开始创建,而是接着问题的编号顺序创建,所以当Pull Request出现在问题列表中时,如果不注意后面的山型的分支图标,根本意识不到这不是一个问题(Issue),而是一个Pull Request。 -.. figure:: /images/issues/issue-list-with-pull-request.png +.. figure:: /images/work-with-others/issue-list-with-pull-request.png :scale: 100 - 图4-63:Pull Request也显示在Issues中 + 图4-64:Pull Request也显示在Issues中 -显示在问题浏览界面中的Pull Request和问题一样,可以为其设置标签、指派负责人、\ -设置里程碑。如图4-64所示。 +显示在问题浏览界面中的Pull Request同问题一样,可以为其设置标签、指派负责人、设置里程碑。如图4-65所示。 -.. figure:: /images/issues/pull-request-update-as-issue.png +.. figure:: /images/work-with-others/pull-request-update-as-issue.png :scale: 100 - 图4-64:可以像更新其他Issue那样更新Pull Request + 图4-65:可以像更新其他Issue那样更新Pull Request -当Pull Request归类到里程碑“Version 4.0”中时,在过滤器打开里程碑“Version 4.0”,\ -可以看到本来已经完成50%的进度,由于新增了一个“问题”(Pull Request),导致\ -进度降低了。如图4-65所示。 +当Pull Request归类到里程碑“Version4.0”中时,在过滤器打开里程碑“Version4.0”,可以看到本来已经完成50%的进度,由于新增了一个“问题”(Pull Request),导致进度降低了。如图4-66所示。 -.. figure:: /images/issues/milestone-progress-with-pull-request.png +.. figure:: /images/work-with-others/milestone-progress-with-pull-request.png :scale: 100 - 图4-65:里程碑进度调整 + 图4-66:里程碑进度调整 -点击编号为“#3”的问题(Pull Request),会进入到Pull Request页面。点击页面中的\ -“Merge pull request”按钮实现Pull Request的合并。如图4-66所示。 +点击编号为“#3”的问题(Pull Request),会进入到Pull Request页面。点击页面中的“Merge pull request”按钮实现Pull Request的合并。如图4-67所示。 -.. figure:: /images/issues/merge-pull-request-for-issue.png +.. figure:: /images/work-with-others/merge-pull-request-for-issue.png :scale: 100 - 图4-66:在线合并Pull Request + 图4-67:在线合并Pull Request -点击“Confirm Merge”确认合并,如图4-67所示。 +点击“Confirm Merge”确认合并,如图4-68所示。 -.. figure:: /images/issues/merge-pull-request-for-issue-confirm.png +.. figure:: /images/work-with-others/merge-pull-request-for-issue-confirm.png :scale: 100 - 图4-67:确认合并Pull Request + 图4-68:确认合并Pull Request -完成合并后,查看该Pull Request,可以看到该Pull Request已经关闭。如图4-68所示。 +完成合并后,查看该Pull Request,可以看到该Pull Request已经关闭。如图4-69所示。 -.. figure:: /images/issues/pull-request-close-for-issue.png +.. figure:: /images/work-with-others/pull-request-close-for-issue.png :scale: 100 - 图4-68:Pull Request自动关闭 - -如果再回到问题浏览界面,能够猜到现在里程碑“Version 4.0”的进度是多少么? + 图4-69:Pull Request自动关闭 -由于关闭了编号为“#3”的Pull Request,以及所合并的Pull Request中对应提交的提交\ -说明的指令同时关闭了编号为“#2”的问题,所以现在里程碑“Version 4.0”关联的所有\ -问题均已关闭。里程碑也显示已关闭,即里程碑完成度为100%。 +如果再回到问题浏览界面,能够猜到现在里程碑“Version4.0”的进度是多少么?由于编号为“#3”的Pull Request的关闭,以及该Pull Request对应的提交中同时关闭了编号为“#2”的问题,所以现在里程碑“Version4.0”关联的所有问题均已关闭,里程碑显示已关闭,即里程碑完成度为100%。 -.. figure:: /images/issues/milestone-closed.png +.. figure:: /images/work-with-others/milestone-closed.png :scale: 100 - 图4-69:里程碑关闭 + 图4-70:里程碑关闭 ---- .. [#] https://github.com/blog/821-mention-somebody-they-re-notified .. [#] https://github.com/blog/811-reply-to-comments-from-email +.. [#] 感谢王胜提供测试账号。 diff --git a/04-work-with-others/060-wiki.rst b/04-work-with-others/060-wiki.rst index b2ed903..94a1ba5 100644 --- a/04-work-with-others/060-wiki.rst +++ b/04-work-with-others/060-wiki.rst @@ -1,228 +1,190 @@ -.. _wiki: - 维基 =============== -维基是Web协同著作平台,可以让任何浏览网页的人都能够方便地参与网页的编辑和创建。\ -这源自于维基如下魔力: +维基是Web协同著作平台,可以让任何浏览网页的人都能够方便地参与网页的编辑和创建。这源自于维基如下魔力: -* 快速更改。修改网页无需复杂的后台修改和网页部署流程,浏览的网页直接提供编辑\ - 按钮,任何查看网页的用户均可在线编辑网页。 -* 简洁语法。编写网页不需要学习复杂的HTML,取而代之的是易学易用的格式化文本\ - (维基语法),有的维基还提供图形化编辑界面。 -* 版本控制。熟悉Git的人,可以把维基看作是Web的版本控制。历次修改都记录在案,\ - 历史修订可进行比较,可恢复到历史版本等。 -* 维基链接。页面链接使用\ ``[[页面名称]]``\ 语法,可以非常方便地创建新页面,\ - 并实现页面间的互联。 +* 快速更改。修改网页无需复杂的后台修改和网页部署流程,浏览的网页直接提供编辑按钮,任何查看网页的用户均可在线编辑网页。 +* 简洁语法。编写网页不需要学习复杂的HTML,取而代之的是易学易用的格式化文本(维基语法),有的维基还提供图形化编辑界面。 +* 版本控制。熟悉Git的人,可以把维基看作是Web的版本控制。历次修改都记录在案,历史修订可进行比较,可恢复到历史版本等。 +* 维基链接。页面链接使用 ``[[页面名称]]`` 语法,可以非常方便地创建新页面,并实现页面间的互联。 GitHub提供了维基模块,方便项目团队创建社区驱动和维护的项目文档。 -.. _wiki-init: - 维基初始化 ------------- -GitHub的维基模块可以通过项目管理页面控制开启或关闭,默认开启,如图4-70所示。\ -因为GitHub提供了项目展示的多种途径,一些小项目如果觉得用\ ``README``\ 文件构建\ -项目说明,或者用\ ``gh-pages``\ 分支维护项目主页就足够了,大可关闭维基模块。 +GitHub的维基模块默认开启。对于一些小项目,如果觉得用 ``README`` 文件构建的项目说明,或者用 ``gh-pages`` 分支维护项目主页就足够了,可以通过项目管理页面开启或关闭维基。如图4-71所示。 -.. figure:: /images/wiki/project-admin-features-wiki.png +.. figure:: /images/work-with-others/project-admin-features-wiki.png :scale: 100 - 图4-70:开启或关闭Wiki模块 + 图4-71:开启或关闭Wiki模块 -项目启用维基后,进入维基页面,如图4-71所示,会发现维基页面并没有自动创建,\ -还需要进行初始化。 +项目启用维基后,进入维基页面,如图4-72所示,会发现维基页面并没有自动创建,还需要进行初始化。 -.. figure:: /images/wiki/wiki-not-exist.png +.. figure:: /images/work-with-others/wiki-not-exist.png :scale: 100 - 图4-71:尚未初始化的维基界面 + 图4-72:尚未初始化的维基界面 -点击“Create Wiki Now”按钮,自动创建维基首页,如图4-72所示。 +点击“Create Wiki Now”按钮,自动创建维基首页,如图4-73所示。 -.. figure:: /images/wiki/wiki-home-init.png +.. figure:: /images/work-with-others/wiki-home-init.png :scale: 100 - 图4-72:自动创建的维基首页 - -.. _use-wiki: + 图4-73:自动创建的维基首页 使用维基 ----------- -自动创建的维基首页只有非常简单的信息,点击编辑按钮,修改维基首页。编辑界面\ -如图4-73所示。 +自动创建的维基首页只有非常简单的信息,点击编辑按钮,修改维基首页。编辑界面如图4-74所示。 -.. figure:: /images/wiki/wiki-edit-init.png +.. figure:: /images/work-with-others/wiki-edit-init.png :scale: 100 - 图4-73:编辑维基首页 + 图4-74:编辑维基首页 编辑界面有6个部分需要重点说明: -1. 页面名称。首页的页面名称为“Home”,不能随意更改,否则无法找到首页,或者页面\ - 之间的跳转会失效。 -2. 工具条。从左至右分别是设置一级标题、二级标题、三级标题、插入链接、图片、\ - 字体加粗、斜体、代码块、列表、编号列表、引用、水平分割线等。 -3. 页面语法格式。默认采用Markdown语法,还可以选用AsciiDoc、Creole等语法。\ - 注意如果改变语法格式,该维基页面的内容需要手工进行调整,而且页面的实际存储\ - 文件的文件扩展名会改变。 -4. 语法帮助。当按下工具条中的帮助按钮会显示本语法帮助表格。 -5. 维基内容编辑框。整个维基页面的内容都在这个编辑框中。鼠标拖动该编辑框右下角\ - 可以对编辑框大小进行缩放。 -6. 可选的修改说明。修改页面时提供说明便于跟踪对页面的历史修订。 - -对初始创建的首页进行更改,如图4-74所示。 - -.. figure:: /images/wiki/wiki-edit-format.png +1. 页面名称。首页的页面名称为“Home”,不能随意更改,否则无法找到首页,或者页面之间的跳转会失效。 +2. 工具条。从左至右分别是设置一级标题、二级标题、三级标题、插入维基链接、其它链接、图片、字体加粗、斜体、代码块、列表、编号列表、引用、水平分割线等。 +3. 维基页面语法格式。默认采用Markdown语法,还可以选用AsciiDoc、Creole等语法。注意如果改变语法格式,该维基页面的内容需要手工进行调整,而且页面的实际存储文件名(扩展名)会改变。 +4. 语法帮助。 +5. 维基内容编辑框。整个维基页面的内容都在这个编辑框中。鼠标拖动该编辑框右下角可以对编辑框大小进行缩放。 +6. 提交说明。如果在保存页面更改时不提供提交说明,系统会自动创建一个提交说明。 + +对初始创建的首页进行更改,如图4-75所示。 + +.. figure:: /images/work-with-others/wiki-edit-format.png :scale: 100 - 图4-74:修改选中文本样式 + 图4-75:修改选中文本样式 -图4-74中,在维基内容编辑框中选择两行文本,然后点击工具栏中的列表按钮,为选中\ -内容应用列表样式。应用新样式后的效果如图4-75所示。然后填写提交说明,点击“Save”\ -按钮保存更改。 +图4-75中,在维基内容编辑框中选择两行文本,然后点击工具栏中的列表按钮,为选中内容应用列表样式。应用新样式后的效果如图4-76所示。然后填写提交说明,点击“Save”按钮保存更改。 -.. figure:: /images/wiki/wiki-edit-save.png +.. figure:: /images/work-with-others/wiki-edit-save.png :scale: 100 - 图4-75:填写提交说明保存更改 + 图4-76:填写提交说明保存更改 -注意图4-75的维基内容中有\ ``[[页面名称]]``\ 样式的语法,这个语法是维基特色的\ -页面链接语法,指向另外的维基页面。实际页面输出如图4-76所示。 +注意图4-76的维基内容中有 ``[[页面名称]]`` 样式的语法,这个语法是维基特色的页面链接语法,指向另外的维基页面。实际页面输出如图4-77所示。 -.. figure:: /images/wiki/wiki-home-simple-wiki-links.png +.. figure:: /images/work-with-others/wiki-home-simple-wiki-links.png :scale: 100 - 图4-76:保存更改后的维基首页 + 图4-77:保存更改后的维基首页 -如果对维基语法\ ``[[页面名称]]``\ 生成的链接标题不满意,还可以用\ -``[[链接标题|页面名称]]``\ 格式创建维基链接。对首页重新做一次修改,修改如下: +如果对维基语法 ``[[页面名称]]`` 生成的链接标题不满意,还可以用 ``[[链接标题|页面名称]]`` 格式创建维基链接。对首页重新做一次修改,修改如下: -* 将\ ``[[HowtoClone]]``\ 改为\ ``[[how to clone|HowtoClone]]``\ 。 -* 将\ ``[[HowtoContribute]]``\ 改为\ ``[[how to contribute|HowtoContribute]]``\ 。 +* 将 ``[[HowtoClone]]`` 改为 ``[[how to clone|HowtoClone]]`` 。 +* 将 ``[[HowtoContribute]]`` 改为 ``[[how to contribute|HowtoContribute]]`` 。 -修改后的首页效果如图4-77所示。 +修改后的首页效果如图4-78所示。 -.. figure:: /images/wiki/wiki-home-update-wiki-links.png +.. figure:: /images/work-with-others/wiki-home-update-wiki-links.png :scale: 100 - 图4-77:修改维基链接标题后的首页 + 图4-78:修改维基链接标题后的首页 -无论怎样更改维基页面都不怕内容丢失,因为维基记录了每一次修订历史,并可以回退\ -任意一次修改。点击维基页面中的“Page History”按钮,查看页面修订历史,如图4-78所示。 +无论如何更改维基页面都不怕内容丢失,因为维基记录了每一次修订历史,并可以回退任意一次修改。点击维基页面中的“Page History”按钮,查看页面修订历史,如图4-79所示。 -.. figure:: /images/wiki/wiki-page-history.png +.. figure:: /images/work-with-others/wiki-page-history.png :scale: 100 - 图4-78:页面修订历史 + 图4-79:页面修订历史 -首页的修订历史记录着维基初始化以来所有的修改,包括修改者、修改时间、提交说明,\ -以及一个可点击的对象ID。点击对象ID查看对应版本的页面。还可以对不同版本的页面进行\ -比较,选中两个版本点击“Compare Revisions”按钮,如图4-79所示。 +首页的修订历史记录着维基初始化以来所有的修改,包括修改者、修改时间、提交说明,以及一个对象ID。点击对象ID可以访问该版本的维基页面。选中两个版本,可以对两个版本进行比较。版本比较的结果如图4-80所示。 -.. figure:: /images/wiki/wiki-page-compare.png +.. figure:: /images/work-with-others/wiki-page-compare.png :scale: 100 - 图4-79:页面版本间比较 + 图4-80:页面版本间比较 -在页面版本间的比较界面中,提供回退此次修改的按钮。点击“Revert Changes”按钮\ -(图4-79所示),可以回退对首页的修改。查看首页的修订历史,会看到回退记录也\ -显示其中,如图4-80所示。 +在页面版本见比较的界面中,提供回退此次修改的按钮。点击“Revert Changes”按钮(图4-80所示),可以回退对首页的修改。查看首页的修订历史,会看到回退记录也显示其中,如图4-81所示。 -.. figure:: /images/wiki/wiki-reverted.png +.. figure:: /images/work-with-others/wiki-reverted.png :scale: 100 - 图4-80:包含回退记录的页面修订历史 + 图4-81:包含回退记录的页面修订历史 -在维基中创建新页面有多种方法,可以点击页面中的“New Page”按钮,也可以像我们\ -之前做的那样先在页面中用\ ``[[页面名称]]``\ 格式嵌入维基链接,然后在生成的\ -页面中可以看到指向新页面的链接,当然这些链接所指向的页面并不存在。 +在维基中创建新页面有多种方法,可以点击页面中的“New Page”按钮,也可以像我们之前做的那样先在页面中用 ``[[页面名称]]`` 格式嵌入维基链接,然后在生成的页面中可以看到指向新页面的链接,当然这些链接所指向的页面并不存在。 -.. figure:: /images/wiki/wiki-newpage.png +.. figure:: /images/work-with-others/wiki-newpage.png :scale: 100 - 图4-81:页面中的维基链接 + 图4-82:页面中的维基链接 -如图4-81所示,点击页面中指向不存在维基页面的链接,会自动开启创建新页面的\ -对话框,如图4-82所示。 +如图4-82所示,点击页面中指向不存在维基页面的链接,会自动开启创建新页面的对话框,如图4-83所示。 -.. figure:: /images/wiki/wiki-newpage-edit.png +.. figure:: /images/work-with-others/wiki-newpage-edit.png :scale: 100 - 图4-82:创建新维基页面 + 图4-83:创建新维基页面 -输入维基页面的内容,然后填写提交说明,点击“Save”按钮,保存新页面。生成的\ -新页面如图4-83所示。 +输入维基页面的内容,然后填写提交说明,点击“Save”按钮,保存新页面。生成的新页面如图4-84所示。 -.. figure:: /images/wiki/wiki-newpage-created.png +.. figure:: /images/work-with-others/wiki-newpage-created.png :scale: 100 - 图4-83:生成的新页面 + 图4-84:生成的新页面 -如果当前用户对页面具有写权限,则在页面左下角会看到一个删除本页面的链接。点击\ -“Delete this page”链接并经确认后会删除页面。然后继续在维基中操作,如创建另外\ -一个新页面\ ``HowtoContribute``\ 。 +如果当前用户对页面具有写权限,则在页面左下角会看到一个删除本页面的链接。点击“Delete this page”链接,弹出删除确认对话框,如图4-85所示。 -如果对之前删除页面\ ``Howtoclone``\ 的操作后悔,可以通过下面方法找回。 +.. figure:: /images/work-with-others/wiki-delete-page.png + :scale: 100 -* 访问菜单中的“Wiki History”项,显示整个维基的修订记录(不是某个页面的修订\ - 记录)。如图4-84所示。 + 图4-85:删除页面确认对话框 - .. figure:: /images/wiki/wiki-history.png - :scale: 100 - - 图4-84:维基修订记录 +继续对维基进行更改,如创建另外一个新页面 ``HowtoContribute`` 。若对之前删除页面的操作后悔,可以通过下面方法找回。访问菜单中的“Wiki History”项,显示整个维基的修订记录(不是某个页面的修订记录)。如图4-86所示。 -* 从图4-84可见上面第二条记录就是删除\ ``HowtoClone``\ 页面的操作,选择该记录\ - 及前一次记录,执行版本比较,如图4-85所示。 +.. figure:: /images/work-with-others/wiki-history.png + :scale: 100 - .. figure:: /images/wiki/wiki-compare-drop-page.png - :scale: 100 - - 图4-85:版本比较 + 图4-86:维基修订记录 -* 点击“Revert Changes”按钮,可以取消页面删除动作。更新后的维基修订历史如图4-86所示。 +从图4-86可见上面第二条记录就是删除 ``HowtoClone`` 页面的操作,选择该记录及前一次记录,执行版本比较,如图4-87所示。 - .. figure:: /images/wiki/wiki-page-restored.png - :scale: 100 - - 图4-86:还原修订后的维基修订记录 +.. figure:: /images/work-with-others/wiki-compare-drop-page.png + :scale: 100 -* 查看维基页面列表,可以看到页面\ ``Howtoclone``\ 已经被找回。 + 图4-87:版本比较 - .. figure:: /images/wiki/wiki-pages.png - :scale: 100 - - 图4-87:维基页面列表 +点击“Revert Changes”按钮,可以取消页面删除动作。更新后的维基修订历史如图4-88所示。 + +.. figure:: /images/work-with-others/wiki-page-restored.png + :scale: 100 + + 图4-88:还原修订后的维基修订记录 + +查看维基页面列表,可以看到页面 ``Howtoclone`` 已经被找回。 + +.. figure:: /images/work-with-others/wiki-pages.png + :scale: 100 + + 图4-89:维基页面列表 -.. _git-backend-wiki: 维基与Git ------------ -随着对GitHub维基的深入使用,可能会遇到下面的问题:如何嵌入图片?多人编辑时\ -如何避免冲突?解决这几个问题的办法就是用Git操作维基。在之前查看维基修订历史,\ -以及进行版本间比较时可能已经看出和Git是如何的相似,实际上GitHub的维基页面\ -就是用Git版本库实现的。 +随着对GitHub维基的深入使用,可能会遇到下面的问题:如何嵌入图片?多人编辑时如何避免冲突?解决这几个问题的办法就是用Git操作维基。在之前查看维基修订历史,以及进行版本间比较时可能已经看出和Git是如何相似,实际上GitHub的维基页面就是用Git版本库实现的。 -在维基页面访问菜单中的“Git Access”项,会看到用Git访问维基页面的方法。如图4-88所示。 +在维基页面访问菜单中的“Git Access”项,会看到如何用Git访问维基页面的方法。如图4-90所示。 -.. figure:: /images/wiki/wiki-git-access.png +.. figure:: /images/work-with-others/wiki-git-access.png :scale: 100 - 图4-88:用Git访问维基 + 图4-90:用Git访问维基 -对于项目\ ``gotgithub/helloworld``\ 来说,用Git克隆其维基,用如下命令: +对于项目 ``gotgithub/helloworld`` 来说,用Git克隆其维基,用如下命令: :: $ git clone git@github.com:gotgithub/helloworld.wiki.git -进入到刚刚克隆的\ ``helloworld.wiki``\ 工作区中,查看包含的文件,会看到有三个文件。 +进入到刚刚克隆的 ``helloworld.wiki`` 工作区中,查看包含的文件,会看到有三个文件。 :: @@ -230,34 +192,27 @@ GitHub的维基模块可以通过项目管理页面控制开启或关闭,默 $ ls Home.md Howtoclone.creole Howtocontribute.md -三个文件对应于三个维基页面,文件名就是维基的页面名称,而扩展名对应于采用的\ -维基语法。以\ ``.md``\ 扩展名结尾的页面采用Markdown语法,而以\ ``.creole``\ -结尾的文件采用Creole标准维基语法。 +三个文件对应于三个维基页面,文件名就是维基的页面名称,而扩展名对应于采用的维基语法。以 ``.md`` 扩展名结尾的页面采用Markdown语法,而以 ``.creole`` 结尾的文件采用Creole标准维基语法。 -下面就通过Git在维基版本库中添加一个图片。添加图片的操作只通过GitHub维基的Web\ -界面是很难实现的,而使用Git则易如反掌。 +下面就通过Git在维基版本库中添加一个图片。添加图片的操作只通过GitHub维基的Web界面是很难实现的,而使用Git则易如反掌。 -* 创建一个名为\ ``images``\ 目录。这个目录并非必须,只是为了易于管理。 +* 创建一个名为 ``images`` 目录。这个目录并非必须,只是为了易于管理。 :: $ mkdir images - $ cd images -* 在\ ``images``\ 目录中添加图片。 - - 下面的操作从GitHub官方版本库中下载图片\ ``octocat.png``\ 并进行适当缩放。 +* 复制一个图片到 ``images`` 目录。 :: - $ wget https://github.com/github/media/raw/master/octocats/octocat.png - $ mogrify -resize '200' octocat.png + $ cp /path/to/images/octocat.png images/ * 将图片添加到暂存区并提交。 :: - $ git add octocat.png + $ git add images $ git commit -m "add sample image." * 将本地提交推送到GitHub远程版本库。 @@ -266,44 +221,30 @@ GitHub的维基模块可以通过项目管理页面控制开启或关闭,默 $ git push -完成推送后,访问下面的网址可以看到刚刚上传的图片: - -:: - - https://github.com/gotgithub/helloworld/wiki/images/octocat.png - -接下来在维基页面中引用图片。嵌入图片的Markdown语法是:\ -``![Alt text here](Image URL here)``\ 。当然可以通过编辑本地版本库\ -``gotgithub/helloworld.wiki.git``\ 中的文件,但通过GitHub维基编辑界面嵌入\ -图片无需记忆复杂的语法。如图4-89所示。 +接下来在维基页面中引用图片,嵌入图片的Markdown语法是: ``![Alt text here](Image URL here)`` 。当然可以通过本地编辑 ``gotgithub/helloworld.wiki.git`` 版本库中的文件,但通过GitHub维基编辑界面嵌入图片无需记忆复杂的语法。如图4-91所示。 -.. figure:: /images/wiki/wiki-insert-image.png +.. figure:: /images/work-with-others/wiki-insert-image.png :scale: 100 - 图4-89:在维基页面中嵌入图片 + 图4-91:在维基页面中嵌入图片 -点击“Preview”按钮,可以在保存前查看效果。在图4-90所示的预览界面中可以看到\ -修改后的效果。 +点击“Preview”按钮,可以在保存前查看效果。在图4-92所示的预览界面中可以看到修改后的效果。 -.. figure:: /images/wiki/wiki-insert-image-preview.png +.. figure:: /images/work-with-others/wiki-insert-image-preview.png :scale: 100 - 图4-90:预览效果 + 图4-92:预览效果 -多人同时编辑一个维基页面会引起冲突,先提交的用户会成功,其他用户的编辑界面\ -马上会显示冲突警告,并且保存按钮也被置灰,如图4-91所示。 +多人同时编辑一个维基页面会引起冲突,先提交的用户会成功,其他用户的编辑界面马上会显示冲突警告,并且保存按钮也被置灰,如图4-93所示。 -.. figure:: /images/wiki/wiki-edit-conflict.png +.. figure:: /images/work-with-others/wiki-edit-conflict.png :scale: 100 - 图4-91:编辑冲突 + 图4-93:编辑冲突 -GitHub的维基编辑界面没有提供冲突解决的工具,而利用Git本身强大的冲突解决功能\ -可以很容易地解决这一难题。 +GitHub的维基编辑界面没有提供冲突解决的工具,而通过本地克隆维基版本库,利用Git本身强大的冲突解决功能可以很容易地解决这一难题。 -例如用户\ ``gotgithub``\ 编辑维基首页\ ``Home``\ 遇到编辑冲突,为防止数据丢失,\ -先将编辑框中的维基文本拷贝并粘贴到一个临时文件中,如文件中\ -``/path/to/draft.md``\ 。然后进行如下操作将\ ``draft.md``\ 中内容合并到维基页面中。 +* 以 ``gotgithub`` 用户编辑维基首页 ``Home`` 遇到编辑冲突。将编辑框中的维基文本保存到文件中,如 ``/path/to/saved.md`` 。 * 如果本地已经克隆维基版本库,则执行下面命令更新。 @@ -319,119 +260,120 @@ GitHub的维基编辑界面没有提供冲突解决的工具,而利用Git本 $ git clone git@github.com:gotgithub/helloworld.wiki.git $ cd helloworld.wiki -* 用Git命令查看版本库的历史,以便找出发生冲突的原始版本。 - - 从下面的输出可以看出我们编辑的版本是基于提交\ ``fbb4bb4``\ ,由于用户\ - ``incredible``\ 先于我们完成了对维基页面的修改以致发生了冲突。 +* 用Git命令查看版本库的历史,以便找出发生冲突的原始版本。从下面的输出可以看出我们编辑的版本是基于提交 ``2f5d65f`` ,由于用户 ``ossxp-com`` 早于我们完成了对维基页面的修改,所以发生了冲突。 :: $ git log -3 --pretty=short - commit 5ff5d998bb6cf99337813915282df94701d17ea0 - Author: incredible + commit 67f1378f3bdf8ca706efae0d77eb1746795f3607 + Author: ossxp-com - Add a note as image link broken if url without a end slash. + Add note: if can not see the image, it is because the URL ends without a slash('/'). - commit fbb4bb4f330bacf765d51736359b0a3e81ed945b + commit 2f5d65fc64484ed659d0c5ffd100a976257a4a7e Author: gotgithub - Insert image in page. + Add link to octocat image. - commit 94182c2b57ebce1f1bf8a310f78df87ae8e8219a + commit a36da9c19a03ed45f8cfce86f86b5055ef661e55 Author: gotgithub add sample image. -* 基于提交\ ``fbb4bb4``\ 建立分支,如分支\ ``mywiki``\ 。 +* 基于提交 ``2f5d65f`` 建立分支,如分支 ``myhack`` 。 :: - $ git checkout -b mywiki fbb4bb4 + $ git checkout -b myhack 2f5d65f -* 将保存的\ ``draft.md``\ 覆盖欲修改的文件,如\ ``Home.md``\ 。 +* 将保存的 ``saved.md`` 覆盖欲修改的文件,如 ``Home.md`` 。 :: - $ cp /path/to/draft.md Home.md + $ cp /path/to/saved.md Home.md * 提交修改。 :: $ git add -u - $ git commit -m "Use absolute image link." + $ git commit -m "My hack on Home page." -* 切换到\ ``master``\ 分支。 +* 切换到 ``master`` 分支。 :: $ git checkout master -* 合并我们在\ ``mywiki``\ 分支的修改。 +* 合并我们在 ``myhack`` 分支的修改。 :: - $ git merge mywiki + $ git merge myhack Auto-merging Home.md - CONFLICT (content): Merge conflict in Home.md - Automatic merge failed; fix conflicts and then commit the result. + Merge made by recursive. + Home.md | 1 - + 1 files changed, 0 insertions(+), 1 deletions(-) -* 调用图形工具解决冲突。 +* 查看合并后的提交关系图。 :: - $ git mergetool - -* 提交并查看合并后的提交关系图。 - - :: - - $ git commit -m "merge with incredible's edit." $ git log --oneline --graph -4 - * d33b55a merge with incredible's edit. - |\ - | * 121c3b2 Use absolute image link. - * | 5ff5d99 Add a note as image link broken if url without a end slash. - |/ - * fbb4bb4 Insert image in page. + * ca3bb71 Merge branch 'myhack' + |\ + | * 1c911e3 My hack on Home page. + * | 67f1378 Add note: if can not see the image, it is because the URL ends without a slash('/'). + |/ + * 2f5d65f Add link to octocat image. -* 查看用户\ ``incredible``\ 的修改。 +* 查看用户 ``ossxp-com`` 的修改。 :: - - $ git show --oneline HEAD^1 - 5ff5d99 Add a note as image link broken if url without a end slash. + + $ git show HEAD^1 + commit 67f1378f3bdf8ca706efae0d77eb1746795f3607 + Author: ossxp-com + Date: Wed Aug 24 03:38:03 2011 -0700 + + Add note: if can not see the image, it is because the URL ends without a slash('/'). + diff --git a/Home.md b/Home.md - index 6ada8e8..0bca3ec 100644 + index 3aee619..91ece10 100644 --- a/Home.md +++ b/Home.md - @@ -1,5 +1,7 @@ + @@ -2,7 +2,9 @@ This is a sample project for the book "GotGitHub". + Hello GitHub. - +**Note**: if can not see the following image, add a slash('/') at the end of the URL. + -![GitHub's Octocat](images/octocat.png) + +![GitHub's Octocat](images/octocat.png) + - ![GitHub Octocat](images/octocat.png) + +**Note**: if can not see this image, add a slash('/') at the end of the URL. - ## HOWTOs - -* 查看用户\ ``gotgithub``\ 的修改。 + # HOWTOs + * To access the repository of this project see: [[HowtoClone]] + +* 查看用户 ``gotgithub`` 的修改。 :: - $ git show --oneline HEAD^2 - 121c3b2 Use absolute image link. + $ git show HEAD^2 + commit 1c911e3163c63c97d11482a3daee070c72ce3772 + Author: gotgithub + Date: Wed Aug 24 18:47:00 2011 +0800 + + My hack on Home page. + diff --git a/Home.md b/Home.md - index 6ada8e8..cdb9167 100644 + index 3aee619..ca85fda 100644 --- a/Home.md +++ b/Home.md - @@ -1,6 +1,6 @@ + @@ -1,4 +1,3 @@ + -# About This is a sample project for the book "GotGitHub". + Hello GitHub. - -![GitHub Octocat](images/octocat.png) - +![GitHub Octocat](https://github.com/gotgithub/helloworld/wiki/images/octocat.png) - - ## HOWTOs - * To access the repository of this project see: [[HowtoClone]] * 将本地合并后的版本库推送到GitHub。 @@ -439,13 +381,9 @@ GitHub的维基编辑界面没有提供冲突解决的工具,而利用Git本 $ git push -再来看看推送后GitHub的维基修订历史,和本地版本库看到的历史是一致的,如图4-92所示。 +再来看看推送后GitHub的维基修订历史,和本地版本库看到的历史是一致的,如图4-94所示。 -.. figure:: /images/wiki/wiki-pushed-history.png +.. figure:: /images/work-with-others/wiki-pushed-history.png :scale: 100 - 图4-92:推送后的维基修订历史 - -GitHub维基背后的引擎名为Gollum,GitHub已将其开源,项目网址:\ -https://github.com/github/gollum 。安装Gollum,在克隆的维基版本库中运行\ ``gollum``\ -就可以在本地启动维基服务。 + 图4-94:推送后的维基修订历史 diff --git a/04-work-with-others/index.rst b/04-work-with-others/index.rst index 2e2de96..1f38e6d 100644 --- a/04-work-with-others/index.rst +++ b/04-work-with-others/index.rst @@ -1,9 +1,6 @@ -.. _cooperate: - 工作协同 ******************** -项目落户GitHub后,一定希望有越来越多的人能参与其中。GitHub提供了包括传统的\ -问题追踪系统、维基,还包括了分布式版本控制系统特有的协同工具。 +项目落户GitHub后,一定希望有越来越多的人能参与其中。GitHub提供了包括传统的问题追踪系统、维基,还包括了分布式版本控制系统特有的协同工具。 .. toctree:: :maxdepth: 1 diff --git a/05-commercial-github/010-non-free-plans.rst b/05-commercial-github/010-non-free-plans.rst new file mode 100644 index 0000000..129ebd3 --- /dev/null +++ b/05-commercial-github/010-non-free-plans.rst @@ -0,0 +1,75 @@ +GitHub收费方案 +=============== + +访问网址 https://github.com/plans 可以看到GitHub提供的不同的服务方案列表。 + +.. figure:: /images/commercial-products/available-plans.png + :scale: 100 + + 图5-1:GitHub服务方案列表 + +图5-1中显示了GitHub的三类(8种)服务方案: + +* 第一类是免费方案。免费用户账号可以创建任意数量的开放式项目(版本库),并且可以为开放式项目设置任意数量的协同者。 +* 第二类是需要付费的个人账号方案。付费的个人账号允许托管私有版本库,即可以创建只有自己及指定的私有协同者才能够访问的版本库,而其他人不能访问。根据允许创建的私有版本库数量及私有版本库协同者数量,提供了三种收费标准(7美元/月、12美元/月 和 22美元/月)。 +* 第三类是需要付费的组织账号方案。使用付费的组织账号,可以突破私有项目的协同者数量限制,并使用更易管理的团队(Team)对项目进行授权。关于如何通过团队配置授权参见“4.3. 组织和团队”。组织账号的付费标准较个人账号更高(有25美元/月、50美元/月、100美元/月 和 200美元/月),但同时也可以创建更多的私有版本库和拥有更大的托管空间。 + +用户可以随时升级或降级自己在GitHub上的服务方案。点击菜单中的“Account Settings”可以看到当前所选方案,如图5-2所示。 + +.. figure:: /images/commercial-products/plan-status.png + :scale: 100 + + 图5-2:用户所选方案及状态 + +点击图5-2中的“Change plan”按钮,进入到更换GitHub服务方案页面,如图5-3所示。 + +.. figure:: /images/commercial-products/change-plan.png + :scale: 100 + + 图5-3:更换方案 + +选择适合的收费方案并付款后,即可完成服务方案的升级。 + +当 gotgithub 用户升级为付费账号后,创建新版本库时就可以通过新的选项创建私有版本库了。即在创建版本库时,不选择默认的“Anyone”,而是选择“Only the people I specify”可以创建私有版本库,如图5-4所示。 + +.. figure:: /images/commercial-products/new-private-repository.png + :scale: 100 + + 图5-4:创建私有版本库 + +通过版本库的管理界面,可以随时将版本库的状态在公开和私有之间切换,如图5-5所示。 + +.. figure:: /images/commercial-products/private-repos-settings.png + :scale: 100 + + 图5-5:私有版本库管理界面 + +付费账号的公开版本库没有协同者数量上的限制,但是私有版本库却存在协同者数量上的限制。如图5-6所示,当私有版本库的协同者数量超出所选GitHub付费方案的限额后,会显示“OVERLIMIT”的警告,不过超出限额的协同者依然可以操作私有版本库。 + +.. figure:: /images/commercial-products/add-private-collaborators.png + :scale: 100 + + 图5-6:添加私有协同者 + +组织是一类特殊的不能登录的用户账号。如果要对组织账号进行配置,需要先以组织所有者的用户账号登录,再通过切换上下文的方式访问组织账号。图5-7就是以 gotgithub 用户账号登录后,切换到 GotGitOrg 组织账号的管理界面。 + +.. figure:: /images/commercial-products/org-plan-status.png + :scale: 100 + + 图5-7:团队账号的所选方案及状态 + +在图5-7所示的组织账号管理界面中显示了组织账号当前的GitHub方案,点击其中的“Change plan”按钮,显示如图5-8所示界面,可对组织账号的GitHub方案进行升级或降级。 + +.. figure:: /images/commercial-products/org-change-plan.png + :scale: 100 + + 图5-8:团队账号更换方案 + +当为组织账号选择一个付费方案后,就可以在组织的账号下创建私有版本库,并以团队方式管理该私有版本库的授权。图5-9就是一个私有版本库 ``GotGitOrg/NonPublicRepo`` 的团队设置界面。 + +.. figure:: /images/commercial-products/org-private-repo-settings.png + :scale: 100 + + 图5-9:团队的私有版本库授权设置 + + diff --git a/05-commercial-github/020-github-fi.rst b/05-commercial-github/020-github-fi.rst new file mode 100644 index 0000000..8653bf2 --- /dev/null +++ b/05-commercial-github/020-github-fi.rst @@ -0,0 +1,27 @@ +GitHub:FI +=========================== +想要在企业内部架设自己的GitHub服务?答案就是GitHub:FI。 + +.. figure:: /images/commercial-products/github-fi.png + :scale: 100 + + 图5-10:GitHub:FI + +GitHub:FI是GitHub Firewall Install的缩写,含义为在企业的防火墙内部架设GitHub服务。对于那些出于隐私或法律原因而不能将代码托管到第三方平台中的企业,用GitHub:FI在企业内部架设专有GitHub服务,可以在保证数据安全的同时,使用GitHub进行团队协同。 + +因为GitHub:FI采用了和GitHub近乎相同的代码,因此会使用GitHub,就会使用GitHub:FI。至于GitHub:FI的部署,因为采用了BitRock的打包和部署方案 [#]_ ,所以可以非常方便的在Linux平台(Ubuntu、Debian或Gentoo)上安装。 + +GitHub:FI的网站 [#]_ 中提供了演示录像,详细介绍了GitHub:FI的安装和使用。图5-11就是演示录像中介绍如何安装的画面。 + +.. figure:: /images/commercial-products/github-fi-tour.png + :scale: 100 + + 图5-11:GitHub:FI演示画面 + +GitHub:FI的购买或试用,访问GitHub:FI网站并和销售人员联系 [#]_ 。 + +---- + +.. [#] https://github.com/blog/441-announcing-github-fi +.. [#] http://fi.github.com/tour.html +.. [#] http://fi.github.com/pricing.html diff --git a/05-commercial-github/github-enterprise.rst b/05-commercial-github/github-enterprise.rst deleted file mode 100644 index d1176e9..0000000 --- a/05-commercial-github/github-enterprise.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. _github-enterprise: - -GitHub企业版 -=========================== -出于隐私或法律原因而不能将代码托管到第三方平台的企业,可能希望在企业内部架设\ -专有的GitHub服务,能做到么?答案就是GitHub企业版(GitHub Enterprise)。 - -网址:\ https://enterprise.github.com/\ 。 - -GitHub企业版搭建在企业本地网络中,因此企业拥有对版本库和项目完整的控制权限。\ -GitHub企业版包含了GitHub上所有的好东西:提交历史、代码浏览、比较视图、\ -Pull Requests、问题追踪、维基、Gists、组织和团队管理、强大的API,和漂亮的界面,\ -因此会使用GitHub就会使用GitHub企业版。此外企业版还增加了对LDAP和CAS支持功能,\ -以便和企业现有的认证系统整合等等\ [#]_\ 。 - -GitHub企业版不像它的前身GitHub:FI\ [#]_\ 那样通过下载软件包进行安装和部署,\ -而是提供基于虚拟机的解决方案。即GitHub企业版以OVF虚拟机文件格式发布,可以运行\ -在多种虚拟机平台,如:VMWare、VirtualBox、Oracle VM、\ -Red Hat Enterprise Virtualization和IBM POWER。\ -使用OVF格式让GitHub企业版的部署更加轻松。 - -GitHub企业版根据用户数量收取年费,入门级的价格为20用户每年5,000美金。如果用户数\ -少,建议采用付费的GitHub托管账号。购买更多用户许可,访问GitHub企业版网站,\ -那儿有一个报价生成器,如图5-10所示。 - -.. figure:: /images/commercial-products/github-enterprise-pricing.png - :scale: 100 - - 图5-10:GitHub企业版报价生成器 - ----- - -.. [#] https://github.com/blog/978-introducing-github-enterprise -.. [#] GitHub:FI是GitHub Firewall Install的缩写,含义为在企业的防火墙内部架设\ - GitHub服务,现已升级为GitHub Enterprise。 diff --git a/05-commercial-github/index.rst b/05-commercial-github/index.rst index 30f086f..8559567 100644 --- a/05-commercial-github/index.rst +++ b/05-commercial-github/index.rst @@ -1,15 +1,10 @@ -.. _non-free: - 付费服务 ******************** -GitHub神奇的协同工具使得开源项目的创建和协同更加简单、高效。有些人可能会提出\ -疑问:能否把GitHub用于私有项目呢?即能否只允许指定的用户访问项目和版本库,\ -而其他人不能访问呢?能否在企业内部架设一个一模一样的GitHub服务呢?GitHub\ -针对这些需求提供了解决方案,这些解决方案需要或多或少地付出一定费用。 +GitHub神奇的协同工具使得开源项目的创建和协同更加简单、高效。有些人可能会提出疑问:能否把GitHub用于私有项目呢?即能否只允许指定的用户访问项目和版本库,而其他人不能访问呢?能否在企业内部架设一个一模一样的GitHub服务呢?GitHub针对这些需求提供了解决方案,这些解决方案需要或多或少地付出一定费用。 .. toctree:: :maxdepth: 1 - non-free-plans.rst - github-enterprise.rst + 010-non-free-plans + 020-github-fi diff --git a/05-commercial-github/non-free-plans.rst b/05-commercial-github/non-free-plans.rst deleted file mode 100644 index 3295e58..0000000 --- a/05-commercial-github/non-free-plans.rst +++ /dev/null @@ -1,93 +0,0 @@ -.. _github-plans: - -GitHub收费方案 -=============== - -访问网址 https://github.com/plans 可以看到GitHub提供的不同的服务方案列表。 - -.. figure:: /images/commercial-products/available-plans.png - :scale: 100 - - 图5-1:GitHub服务方案列表 - -图5-1中显示了GitHub的三类(8种)服务方案: - -* 第一类是免费方案。免费用户账号可以创建任意数量的开放式项目(版本库),并且\ - 可以为开放式项目设置任意数量的协同者。 -* 第二类是需要付费的个人账号方案。付费的个人账号允许托管私有版本库,即可以\ - 创建只有自己及指定的私有协同者才能够访问的版本库,而其他人不能访问。根据允许\ - 创建的私有版本库数量及私有版本库协同者数量,提供了三种收费标准(7美元/月、\ - 12美元/月 和 22美元/月)。 -* 第三类是需要付费的组织账号方案。使用付费的组织账号,可以突破私有项目的\ - 协同者数量限制,并使用更易管理的团队(Team)对项目进行授权。关于如何通过\ - 团队配置授权参见“4.3. 组织和团队”。组织账号的付费标准较个人账号更高\ - (有25美元/月、50美元/月、100美元/月 和 200美元/月),但同时也可以创建更多\ - 的私有版本库和拥有更大的托管空间。 - -用户可以随时升级或降级自己在GitHub上的服务方案。点击菜单中的“Account Settings”\ -可以看到当前所选方案,如图5-2所示。 - -.. figure:: /images/commercial-products/plan-status.png - :scale: 100 - - 图5-2:用户所选方案及状态 - -点击图5-2中的“Change plan”按钮,进入到更换GitHub服务方案页面,如图5-3所示。 - -.. figure:: /images/commercial-products/change-plan.png - :scale: 100 - - 图5-3:更换方案 - -选择适合的收费方案并付款后,即可完成服务方案的升级。 - -当 gotgithub 用户升级为付费账号后,创建新版本库时就可以通过新的选项创建\ -私有版本库了。即在创建版本库时,如果不选择默认的“Anyone”,而是选择\ -“Only the people I specify”可以创建私有版本库,如图5-4所示。 - -.. figure:: /images/commercial-products/new-private-repository.png - :scale: 100 - - 图5-4:创建私有版本库 - -通过版本库的管理界面,可以随时将版本库的状态在公开和私有之间切换,如图5-5所示。 - -.. figure:: /images/commercial-products/private-repos-settings.png - :scale: 100 - - 图5-5:私有版本库管理界面 - -付费账号的公开版本库没有协同者数量上的限制,但是私有版本库却存在协同者数量上\ -的限制。如图5-6所示,当私有版本库的协同者数量超出所选GitHub付费方案的限额后,\ -会显示“OVERLIMIT”的警告,不过超出限额的协同者依然可以操作私有版本库。 - -.. figure:: /images/commercial-products/add-private-collaborators.png - :scale: 100 - - 图5-6:添加私有协同者 - -组织是一类特殊的不能登录的用户账号。如果要对组织账号进行配置,需要先以组织\ -所有者的用户账号登录,再通过切换上下文的方式访问组织账号。图5-7就是以\ -gotgithub用户账号登录后,切换到 GotGitOrg 组织账号的管理界面。 - -.. figure:: /images/commercial-products/org-plan-status.png - :scale: 100 - - 图5-7:团队账号的所选方案及状态 - -在图5-7所示的组织账号管理界面中显示了组织账号当前的GitHub方案,点击其中的\ -“Change plan”按钮,显示如图5-8所示界面,可对组织账号的GitHub方案进行升级或降级。 - -.. figure:: /images/commercial-products/org-change-plan.png - :scale: 100 - - 图5-8:团队账号更换方案 - -为组织账号选择一个付费方案后,就可以在组织的账号下创建私有版本库,并以团队\ -方式管理该私有版本库的授权。图5-9就是一个私有版本库\ ``GotGitOrg/NonPublicRepo``\ -的设置界面。 - -.. figure:: /images/commercial-products/org-private-repo-settings.png - :scale: 100 - - 图5-9:团队的私有版本库设置 diff --git a/06-side-projects/010-gist.rst b/06-side-projects/010-gist.rst new file mode 100644 index 0000000..6c3d0e8 --- /dev/null +++ b/06-side-projects/010-gist.rst @@ -0,0 +1,229 @@ +GitHub:Gist +=============== +在GitHub网站的导航条上就有Gist子网站的链接: https://gist.github.com/ ,在本节我们就揭开其面纱。 + +.. figure:: /images/side-projects/gist-in-github-navbar.png + :scale: 100 + + 图6-1:GitHub上的Gist链接 + +Gist作为一个粘贴数据的工具,就像 Pastie 网站 [#]_ 一样,可以很容易地将数据粘贴在Gist网站中,并在其他网页中引用Gist中粘贴的数据。作为GitHub的一个子网站,很自然地,Gist使用Git版本库对粘贴数据进行维护,这非常酷。 + +数据的粘贴和引用 +----------------- +进入Gist网站的首页,就会看到一个大大的数据粘贴对话框,如图6-2所示。 + +.. figure:: /images/side-projects/gist-homepage.png + :scale: 100 + + 图6-2:Gist网站首页 + +只要提供一行简单的描述、文件名,并粘贴文件内容,即可创建一个新的粘贴。创建新的粘贴时,如果不指定文件名,将由系统自动指派。如图6-3所示。 + +.. figure:: /images/side-projects/gist-create-new.png + :scale: 100 + + 图6-3:创建新的Gist + +每一个新的粘贴称为一个Gist,并拥有唯一的URL。如果选择创建公开的Gist,URL中将使用顺序递增的ID号,如本例创建的Gist的URL地址为: https://gist.github.com/1202870 。 + +若选择创建私有Gist,URL中则采用20位十六进制数字的ID,例如私密Gist: https://gist.github.com/78d67164131ec9e08dfe 。需要指出的是,私有Gist的私密性并不像GitHub私有版本库的私密性那么强,只是其URL没有在用户Gist列表中列出,也不能通过Gist网站搜索到而已。如果用户知道某私密Gist的URL地址,同样可以访问、克隆该私密Gist,甚至创建基于该Gist创建分支(fork)。 + +当一个粘贴创建完毕后,会显示新建立的Gist页面,如图6-4所示。 + +.. figure:: /images/side-projects/gist-created.png + :scale: 100 + + 图6-4:新创建的Gist + +点击其中的“embed”(嵌入)按钮,就会显示一段用于嵌入的JavaScript代码,如图6-5所示。 + +.. figure:: /images/side-projects/gist-embed.png + :scale: 100 + + 图6-5:显示嵌入Java + + +对应的嵌入JavaScript代码如下: + +:: + + + + +将上面的JavaScript代码嵌入到网页(如博客 [#]_ )中,即可在网页中嵌入Gist中粘贴的数据,并保持语法加亮等功能,如图6-6所示。 + +.. figure:: /images/side-projects/gist-embed-in-blog.png + :scale: 100 + + 图6-6:博客中引用Gist数据 + +Gist背后的Git库 +----------------- +创建的每一个Gist的背后都对应着一个Git版本库。例如之前创建的ID为1202870的Gist对应的Git版本库,可以使用两种协议进行访问: + +* Git协议: ``git://gist.github.com/1202870.git`` +* SSH协议: ``git@gist.github.com:1202870.git`` + +可以通过Git命令克隆和操作该版本库。 + +* 克隆该Gist对应的版本库。 + + :: + + $ git clone git@gist.github.com:1202870.git + $ cd 1202870 + +* 查看修改日志。每一次对Gist中文件的修改对应于一次提交。 + + :: + + $ git log + commit 993d28a1319eca314ab2e3f4c46882cf328e5ff9 + Author: GotGitHub + Date: Thu Sep 15 15:41:10 2011 +0800 + + commit 4dd9cfd54e1522d0b62d92dd5f705a61e3fe8778 + Author: GotGitHub + Date: Thu Sep 8 00:46:50 2011 -0700 + + +* 查看最近一次更改。 + + :: + + $ git show HEAD + commit 993d28a1319eca314ab2e3f4c46882cf328e5ff9 + Author: GotGitHub + Date: Thu Sep 15 15:41:10 2011 +0800 + + diff --git a/countdown.rb b/countdown.rb + index a9d747b..9045738 100644 + --- a/countdown.rb + +++ b/countdown.rb + @@ -4,4 +4,8 @@ + require 'Date' + + days=(DateTime.new(2012,10,15)-DateTime.now).ceil + -puts "Maybe #{days} days left." + \ No newline at end of file + +if days >= 0 + + puts "Maybe #{days} days left." + +else + + puts "Passed for #{days.abs} days." + +end + \ No newline at end of file + +Gist网站并没有像GitHub网站那样对于Git版本库提供完整的、近乎复杂的操作界面和工作流支持,而只提供了最基本的操作界面。如图6-7所示。 + +.. figure:: /images/side-projects/gist-git-repo.png + :scale: 100 + + 图6-7:Gist版本库简易操作界面 + +在这个简易的Git版本库操作界面中,左侧是版本库的简介、文件预览以及在线编辑、下载、加注星标 [#]_ 、版本库分支 [#]_ 等相关操作按钮。若以Gist创建者登录,会在右侧看到他人基于该Gist创建分支的情况,但是并不提供GitHub才有的Pull Request等功能。在界面的右侧还显示了Gist修订历史,和之前通过 ``git log`` 命令从Git版本库看到的一样。 + +Greasemonkey +----------------- +Gist除了被用于粘贴数据(如代码块)并在网页中引用之外,还被用户挖掘出了新的应用模式,例如用作Greasemonkey脚本的维护 [#]_ 。 + +Greasemonkey [#]_ 或类似插件为浏览器提供用户端JavaScript扩展功能,最早出现于FireFox浏览器中。其他浏览器也陆续增加了对用户端JavaScript的支持,如Safari的GreaseKit [#]_ 插件,IE的Trixie [#]_ 插件,以及Chrome的Greasemetal插件 [#]_ 。关于如何在浏览器中安装并启用相应的插件,参照相关插件网站的介绍,在此不做过多叙述。 + +当浏览器安装了 Greasemonkey 或类似插件之后,当访问扩展名为 ``.user.js`` 的URL时,会将该URL指向的JavaScript脚本安装在浏览器中,当访问指定的网址时会自动调用相应的JavaScript脚本,修改相关网页内容或添加特效等等。 + +我针对《Git权威指南》官网的测试网页写了一个Greasemonkey示例脚本,可以展示用户端JavaScript的魔法,这个用户端JavaScript脚本保存在Gist中: +https://gist.github.com/1084591 ,如图6-8所示。 + +.. figure:: /images/side-projects/gist-greasemonkey.png + :scale: 100 + + 图6-8:保存Greasemonkey用户端脚本的Gist + +该Greasemonkey脚本的文件名为 ``click_more.user.js`` ,该文件的文件头使用特殊的注释语句为Greasemonkey提供相关的安装和注册信息,内容如下(为方便计添加了行号): + +:: + + 1 // ==UserScript== + 2 // @name Click more for toggle + 3 // @namespace gotgit + 4 // @description Add a toogle effect at the location where anchor with a click-more css. + 5 // @include http://www.ossxp.com/doc/gotgit/demo* + 6 // @include http://gotgit.github.com/gotgit/demo* + 7 // @require http://code.jquery.com/jquery-1.6.2.min.js + 8 // ==/UserScript== + 9 // Copyright 2011, Jiang Xin + +其中第5行和第6行的两条 `include` 语句限定了此用户端JavaScript脚本的应用范围,即只针对指定的URL(使用通配符)执行该脚本。第7行设定脚本依赖,即该脚本依赖jQuery,会在运行前到指定的URL地址加载jQuery脚本。 + +在安装该脚本前,先用浏览器访问网址 http://gotgit.github.com/gotgit/demo.html ,看看不加载用户端JavaScript脚本时网页的模样。该网页中包含一个冗长的网上书店列表,如图6-9所示。 + +.. figure:: /images/side-projects/gist-user-js-apply-before.png + :scale: 100 + + 图6-9:应用用户端JavaScript脚本前的网页内容 + +接下来开始安装该用户端JavaScript脚本。安装非常简单,只要点击图6-8的Gist当中的脚本文件对应的“raw”链接,即点击脚本文件原始内容链接 [#]_ 即可开启安装。这是因为该URL以 ``.user.js`` 结尾,会被Greasemonkey(或类似插件)识别并安装,如图6-10是Greasemonkey弹出的用户端脚本安装界面。 + +.. figure:: /images/side-projects/gist-user-js-install.png + :scale: 100 + + 图6-10:安装用户端JavaScript脚本 + +用户端脚本安装完毕后,再访问同样的测试网页 http://gotgit.github.com/gotgit/demo.html ,会发现网页中出现了一个名为“更多”的可点击链接,冗长的网上书店列表不见了。如图6-11所示。 + +.. figure:: /images/side-projects/gist-user-js-apply-after.png + :scale: 100 + + 图6-11:应用用户端JavaScript脚本后的网页内容 + +如果查看网页源码,会发现该网页中根本没有包含和调用任何JavaScript脚本,只是在页面源码中包含着若干个没有任何实质输出的标签: + +:: + +

+ +实际上正是这些特殊的标签被Greasemonkey自动加载的用户端脚本识别,对HTML网页添加了特效。 + + +命令行操作Gist +----------------- +GitHub开发者还写了一个名为gist的命令行工具对Gist进行操作,地址见 https://github.com/defunkt/gist 。 + +该工具使用Ruby开发,对两个特定的Git风格的配置变量进行如下设置后,即可实现在命令行中自动以特定用户身份登录操作Gist。 + +:: + + $ git config --global github.user "your-github-username" + $ git config --global github.token "your-github-token" + +其中 ``github.token`` 中保存的是用户的API TOKEN,这在“2.1 创建GitHub账号”一节有过介绍。 + +使用gist命令行工具创建新的Gist非常简单。 + +* 创建包含一个文件(如 ``script.py`` )的Gist,使用如下命令。 + + :: + + $ gist script.py + +* 创建包含多个文件的Gist,使用类似如下的命令。 + + :: + + $ gist script.js notes.txt + +如果对命令行操作方式感兴趣,参考gist工具网站的 `README` 文件。 + + +---- + +.. [#] http://pastie.org/ +.. [#] http://blog.ossxp.com/2011/09/2521/ +.. [#] 对感兴趣的Gist进行收藏,参见博客 https://github.com/blog/673-starring-gists 。 +.. [#] 访问他人创建的Gist时,提供分支功能按钮。 +.. [#] https://github.com/blog/302-gist-for-greasemonkey +.. [#] https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/ +.. [#] http://8-p.info/greasekit/ +.. [#] http://www.bhelpuri.net/Trixie/ +.. [#] 版本4之后的Chrome内置了Greasemonkey类似功能,无需额外插件。 +.. [#] https://gist.github.com/raw/1084591/73c3e4dfc827732241ca753fe7bb985c14c9d7ab/click_more.user.js diff --git a/06-side-projects/020-jobs.rst b/06-side-projects/020-jobs.rst new file mode 100644 index 0000000..e207240 --- /dev/null +++ b/06-side-projects/020-jobs.rst @@ -0,0 +1,22 @@ +GitHub:Jobs +=============== +GitHub求职网站 [#]_ ,于2010年8月开通,提供求职招聘服务 [#]_ 。还记得在“第2.1节 创建GitHub账号”介绍的相关内容么?当用户在个人设置中对简历和求职状态进行设置和启用后,GitHub就会帮助用户寻找合适的工作机会,而工作机会就来自于GitHub的求职网站(如图6-12所示)。 + +.. figure:: /images/side-projects/jobs-homepage.png + :scale: 100 + + 图6-12:GitHub求职网站 + +个人用户除了开启求职状态坐等通知外,还可以主动出击,直接到GitHub求职网站上寻找合适的工作机会,整个求职过程是免费的。而作为企业主发布招聘启示则是收费服务,发布招聘启示的流程如图6-13所示。 + +.. figure:: /images/side-projects/jobs-post-process.png + :scale: 100 + + 图6-13:企业主发布招聘启示流程 + +企业发布招聘启示,首先要按照模版填写职位说明及留下供求职着投递简历的邮件地址,然后用信用卡付费,每一个招聘启示的付费标准为350美元/月。一旦付费完成招聘马上生效。GitHub作为程序员的聚集地,无疑是招聘和应聘的理想之地。 + +---- + +.. [#] http://jobs.github.com/ +.. [#] https://github.com/blog/694-github-jobs-launches-tomorrow diff --git a/06-side-projects/030-shop.rst b/06-side-projects/030-shop.rst new file mode 100644 index 0000000..03acf32 --- /dev/null +++ b/06-side-projects/030-shop.rst @@ -0,0 +1,23 @@ +GitHub:Shop +=============== +GitHub商店 [#]_ 销售着一些你在其他地方买不到的小东西——如印着GitHub吉祥物Octocat的纪念品,图6-14展示的就是一款印着Octocat的杯子。 + +.. figure:: /images/side-projects/shop-octocat-mug.jpg + :scale: 100 + + 图6-14:印着Octocat吉祥物的杯子 + +图6-15则是GitHub热卖的一款体恤的前后两面的图案设计 [#]_ 。体恤前面印着GitHub社区编程最核心的理念(fork you),体恤后面则可以用记号笔写下你在GitHub上的主页地址。 + +.. figure:: /images/side-projects/shop-fork-you-shirt.png + :scale: 100 + + 图6-15:超酷的GitHub体恤 + +GitHub商店实际上是架设于Shopify [#]_ 电子商务网站上的网店。GitHub商店并非GitHub主业,销售纪念品可以增强GitHub用户的认同感,而GitHub粉丝可以购买一项“装备”让自己看起来更酷。 + +---- + +.. [#] http://shop.github.com/ +.. [#] https://github.com/blog/676-fork-you +.. [#] http://www.shopify.com/ diff --git a/06-side-projects/svn.rst b/06-side-projects/040-svn.rst similarity index 60% rename from 06-side-projects/svn.rst rename to 06-side-projects/040-svn.rst index 1222402..08066af 100644 --- a/06-side-projects/svn.rst +++ b/06-side-projects/040-svn.rst @@ -1,15 +1,8 @@ -.. _svn-github: - 用SVN操作GitHub ================= -2008年4月1日,GitHub宣布推出基于SVN的SVNHub网站,后证实这是一个愚人节玩笑\ [#]_\ 。\ -2010年愚人节,类似消息再起,可这一次不再是玩笑\ [#]_\ 。即对于GitHub上的\ -每一个Git版本库,现在都可以用SVN命令进行操作。更酷的是 SVN 版本库使用的是\ -和 Git 版本库同样的地址\ [#]_\ 。 +2008年4月1日,GitHub宣布推出基于SVN的SVNHub网站,后证实这是一个愚人节玩笑 [#]_ 。2010年愚人节,类似消息再起,可这一次不再是玩笑 [#]_ 。即对于GitHub上的每一个Git版本库,现在都可以用SVN命令进行操作。更酷的是 SVN 版本库使用的是和 Git 版本库同样的地址 [#]_ 。 -例如用下面的 Git 命令访问本书的 Git 版本库,显示版本库包含的引用。其中分支\ -``master``\ 用于维护书稿,分支\ ``gh-pages``\ 保存书稿编译后的 HTML 网页用于\ -在 GitHub 上显示。 +例如用下面的 Git 命令访问本书的 Git 版本库,显示版本库包含的引用。其中分支 ``master`` 用于维护书稿,分支 ``gh-pages`` 保存书稿编译后的 HTML 网页用于在 GitHub 上显示。 :: @@ -17,8 +10,7 @@ ce5d3dda9b9ce8ec90def1da10181a094bea152f refs/heads/gh-pages c4d370b1b0bafb103de14e104ca18b8c31d80add refs/heads/master -如果使用 SVN 命令访问相同的版本库地址,Git 服务器变身为一个 SVN 服务器,\ -将Git的引用对应为 SVN 风格的分支。如下: +如果使用 SVN 命令访问相同的版本库地址,Git 服务器变身为一个 SVN 服务器,将 Git 的引用对应为 SVN 风格的分支。如下: :: @@ -28,8 +20,7 @@ $ svn ls https://github.com/gotgit/gotgithub/branches gh-pages/ -SVN 支持部分检出,下面命令将整个主线\ ``trunk``\ (相当于 Git 版本库的\ -``master``\ 分支)检出。 +SVN 支持部分检出,下面命令将整个主线 ``trunk`` (对应于 Git 版本库的 ``master`` 分支)检出。 :: @@ -37,21 +28,20 @@ SVN 支持部分检出,下面命令将整个主线\ ``trunk``\ (相当于 Gi A gotgithub/Makefile A gotgithub/README.rst ... + A gotgithub/images/work-with-others/wiki-reverted.png + A gotgithub/images/work-with-others/wiki-reverted.xcf Checked out revision 30. -还可以使用 SVN 命令创建分支,即相当于在 Git 版本库中创建新的引用。测试发现\ -GitHub 尚不支持 SVN 远程拷贝创建分支,需要通过本地拷贝再提交的方式创建新分支。\ -操作如下: +还可以使用 SVN 命令创建分支,即相当于在 Git 版本库中创建新的引用。测试发现 GitHub 尚不支持 SVN 远程拷贝创建分支,需要通过本地拷贝再提交的方式创建新分支。操作如下: -1. 为避免检出版本库所有分支过于耗时,在检出时使用\ ``--depth=empty``\ 参数。 +1. 为避免检出版本库所有分支过于耗时,在检出时使用 ``--depth=empty`` 参数。 :: - $ svn checkout --depth=empty \ - https://github.com/gotgit/gotgithub gotgithub-branches + $ svn checkout --depth=empty https://github.com/gotgit/gotgithub gotgithub-branches Checked out revision 30. -2. 进入到检出目录中,更新出\ ``trunk``\ 和\ ``branches``\ 两个顶级目录。 +2. 进入到检出目录中,更新出 ``trunk`` 和 ``branches`` 两个顶级目录。 :: @@ -62,7 +52,7 @@ GitHub 尚不支持 SVN 远程拷贝创建分支,需要通过本地拷贝再 A branches Updated to revision 30. -3. 通过拷贝从主线\ ``trunk``\ 创建分支\ ``branches/svn-github``\ 。 +3. 通过拷贝从主线 ``trunk`` 创建分支 ``branches/svn-github`` 。 :: @@ -83,7 +73,7 @@ GitHub 尚不支持 SVN 远程拷贝创建分支,需要通过本地拷贝再 Committed revision 31. -5. 用 Git 命令可以看到服务器上创建了一个新的同名引用,并且指向和\ ``master``\ 一致。 +5. 用 Git 命令可以看到服务器上创建了一个新的同名引用,并且指向和 ``master`` 一致。 :: @@ -92,10 +82,9 @@ GitHub 尚不支持 SVN 远程拷贝创建分支,需要通过本地拷贝再 c4d370b1b0bafb103de14e104ca18b8c31d80add refs/heads/master c4d370b1b0bafb103de14e104ca18b8c31d80add refs/heads/svn-github -下面尝试一下用 SVN 命令在新创建的分支\ ``svn-github``\ 中提交。 +下面尝试一下用 SVN 命令在新创建的分支 ``svn-github`` 中提交。 -1. 进入到之前检出完整主线\ ``trunk``\ 的\ ``gotgithub``\ 目录,并将工作区切换\ - 为分支\ ``branches/svn-github``\ 。 +1. 进入到之前检出完整主线 ``trunk`` 的 ``gotgithub`` 目录,并将工作区切换为分支 ``branches/svn-github`` 。 :: @@ -119,8 +108,7 @@ GitHub 尚不支持 SVN 远程拷贝创建分支,需要通过本地拷贝再 Transmitting file data . Committed revision 32. -4. 同样查看 Git 版本库的更新,会发现\ ``svn-github``\ 分支的指向已和\ - ``master``\ 不同。 +4. 同样查看 Git 版本库的更新,会发现 ``svn-github`` 分支的指向已和 ``master`` 不同。 :: @@ -129,6 +117,8 @@ GitHub 尚不支持 SVN 远程拷贝创建分支,需要通过本地拷贝再 c4d370b1b0bafb103de14e104ca18b8c31d80add refs/heads/master 64b80cb5331e28fdfb896e2ab3085779bf6ca019 refs/heads/svn-github +如果曾经有人对 GitHub 只提供唯一的版本库格式(Git)托管表示过怀疑的话,那么今天看到 GitHub 对其他版本控制工具提供的愈发完善的支持,争议应该烟消云散了吧。 + ---- .. [#] https://github.com/blog/31-back-to-subversion diff --git a/06-side-projects/hg-git.rst b/06-side-projects/050-hg-git.rst similarity index 58% rename from 06-side-projects/hg-git.rst rename to 06-side-projects/050-hg-git.rst index ba88655..455780e 100644 --- a/06-side-projects/hg-git.rst +++ b/06-side-projects/050-hg-git.rst @@ -1,14 +1,9 @@ -.. _hg-git: - 用Hg操作GitHub =============== -Hg(又称Mercurial)和 Git 一样也是一个被广泛使用的分布式版本库控制工具。如果\ -一个熟悉 Hg 的开发者参与托管在 GitHub 上的项目,大可不必为更换版本控制工具而\ -苦恼,GitHub 上的一个名为 hg-git\ [#]_\ 的开源项目可以帮上忙。 +Hg(又称Mercurial)和 Git 一样也是一个被广泛使用的分布式版本库控制工具。如果一个熟悉 Hg 的开发者参与托管在 GitHub 上的项目,大可不必为更换版本控制工具而苦恼,GitHub 上的一个名为 hg-git [#]_ 的开源项目可以帮上忙。 -得益于 Hg 的强大的插件扩展机制,安装 hg-git 并将其注册为Hg 插件后可提供Hg\ -操作 Git 版本库的能力。安装 hg-git 可以直接使用 :program:`easy_install` 命令: +得益于 Hg 的强大的插件扩展机制,安装 hg-git 并将其注册为Hg 插件后可提供 Hg 操作 Git 版本库的能力。安装 hg-git 可以直接使用 :program:`easy_install` 命令: :: @@ -24,12 +19,9 @@ Hg(又称Mercurial)和 Git 一样也是一个被广泛使用的分布式版 $ cd schacon-hg-git-* $ sudo easy_install . -插件 hg-git 依赖于 Dulwich 项目,如果在安装过程遇到 Dulwich 无法编译,可能\ -是因为缺乏 C 编译器,或者尚未安装 python-dev 软件包。Dulwich 是一个Python\ -语言的 Git 实现,因此 hg-git 在运行过程中无需 Git 命令行。 +插件 hg-git 依赖于 Dulwich 项目,如果在安装过程遇到 Dulwich 无法编译,可能是因为缺乏 C 编译器,或者尚未安装 python-dev 软件包。Dulwich 是一个 Python 语言的 Git 实现,因此 hg-git 在运行过程中无需 Git 命令行。 -和其他 Hg 插件类似,安装完毕后需要修改Hg配置文件(如文件 :file:`~/.hgrc` )\ -如下,以启用 hg-git 插件以及另外一个必须的 Hg 内置插件 —— bookmarks 插件。 +和其他 Hg 插件类似,安装完毕后需要修改Hg配置文件(如文件 :file:`~/.hgrc` )如下,以启用 hg-git 插件以及另外一个必须的 Hg 内置插件 —— bookmarks 插件。 :: @@ -48,9 +40,7 @@ Hg(又称Mercurial)和 Git 一样也是一个被广泛使用的分布式版 * Git 版本库的分支转换为 Hg 版本库中的 bookmarks。 - 新克隆的 Hg 版本库默认会更新到最新提交(即 tip 版本),未必处于所需的分支上。\ - 用命令\ :command:`hg bookmarks`\ 显示分支列表,命令\ :command:`hg parents`\ - 显示工作区对应的版本。 + 新克隆的 Hg 版本库默认会更新到最新提交(即 tip 版本),未必处于所需的分支上。用命令 :command:`hg bookmarks` 显示分支列表,命令 :command:`hg parents` 显示工作区对应的版本。 :: @@ -67,10 +57,9 @@ Hg(又称Mercurial)和 Git 一样也是一个被广泛使用的分布式版 日期: Fri Dec 31 12:12:42 2010 +0800 摘要: Translate for Chinese. -* 切换到所需的工作分支(如\ ``master``\ 分支)。 +* 切换到所需的工作分支(如 ``master`` 分支)。 - 用\ `hg update -r`\ 命令切换分支。之后执行\ :command:`hg bookmarks`\ 命令会\ - 看到当前工作分支用星号标识出来。 + 用 `hg update -r` 命令切换分支。之后执行 :command:`hg bookmarks` 命令会看到当前工作分支用星号标识出来。 :: @@ -90,15 +79,11 @@ Hg(又称Mercurial)和 Git 一样也是一个被广泛使用的分布式版 jx/v2.3 10:2767ad9d7008 ... -* 使用\ :command:`hg pull`\ 命令和\ :command:`hg push`\ 命令可以实现和\ - Git版本库的同步。 +* 使用 :command:`hg pull` 命令和 :command:`hg push` 命令可以实现和 Git 版本库的同步。 -* 有的命令如\ :command:`hg outgoing`\ 可在 1.7 版本的Hg中运行正常,\ - 但对于高版本库的 Hg 存在兼容性问题。 +* 有的命令如 :command:`hg outgoing` 可在 1.7 版本的 Hg 中运行正常,但对于高版本库的 Hg 存在兼容性问题。 -实际上 hg-git 插件并非只针对 GitHub 的版本库,而是可以支持任意 Git 版本库\ -包括本地 Git 版本库。为了提供对 Git 版本库的透明支持,对 Git 版本库的 URL\ -的写法有特殊要求,即要能够从协议名称区分开 Git 版本库和默认的 Hg 版本库。 +实际上 hg-git 插件并非只针对 GitHub 的版本库,而是可以支持任意 Git 版本库包括本地 Git 版本库。为了提供对 Git 版本库的透明支持,对 Git 版本库的 URL 的写法有特殊要求,即要能够从协议名称区分开 Git 版本库和默认的 Hg 版本库。 * Git协议: diff --git a/06-side-projects/060-client-tools.rst b/06-side-projects/060-client-tools.rst new file mode 100644 index 0000000..cef59c0 --- /dev/null +++ b/06-side-projects/060-client-tools.rst @@ -0,0 +1,46 @@ +客户端工具 +=============== + +GitHub提供的Web服务,在客户端通常只需要浏览器及Git命令行工具就可以满足需要了。而GitHub还开发了一些客户端工具,以便用户有更好的客户端体验。 + +github:mac +----------------------- + +GitHub专为Mac用户开发了一款图形化客户端应用 `github:mac` ,在Mac下操作GitHub更简单。软件下载地址: http://mac.github.com/ 。 + +`github:mac` 可以实现版本库克隆、查看历史、提交、分支管理、与GitHub同步等功能。图6-16展示的是提交界面,在提交界面中同时显示了变更的差异比较,用户可以挑选文件中的部分变更进行提交,显然这个操作要比在命令行中执行 :command:`git add --patch` 或 :command:`git commit --patch` 要更加直观。 + +.. figure:: /images/side-projects/mac-partial-commit.png + :scale: 100 + + 图6-16:筛选文件中的部分更改进行提交 + +`github:mac` 和GitHub深度集成,当配置好关联的GitHub账号后,会自动在本地创建专用的SSH公钥/私钥对文件 :file:`~/.ssh/github_rsa` (如果该文件不存在的话),然后将公钥文件传递到GitHub网站并自动完成配置。新增的SSH公钥文件显示在GitHub网站的账号设置中,如图所示: + +.. figure:: /images/side-projects/mac-new-ssh-pubkey.png + :scale: 100 + + 图6-17:在GitHub上自动添加的SSH公钥 + +同时 `github:mac` 还在本地将新生成的私钥文件添加到 ``ssh-agent`` 认证代理中,这样一旦通过 SSH 协议连接GitHub,首先采用该公钥/私钥对进行身份认证。用下面的命令可以查看添加到 ``ssh-agent`` 中的私钥文件。 + +:: + + $ ssh-add -l + 2048 aa:01:4f:d2:14:ba:5f:9f:8c:dc:b5:9d:44:cd:8e:18 /Users/jiangxin/.ssh/github_rsa (RSA) + +这种透明的公钥认证管理非常酷,对于大多数只使用唯一一个GitHub账号的用户来说是非常方便的。但如果用户拥有多个GitHub账号并需要不时切换账号,这种实现却很糟糕,会导致认证错误。因为当 ``ssh-agent`` 认证代理缓存了私钥后,连接由文件 :file:`~/.ssh/config` 设置的 SSH 别名主机无法使用指定的公钥/私钥对进行认证,导致认证失败。 + +遇到 GitHub 账户 SSH 认证问题,可以运行下面命令清空 ``ssh-agent`` 缓存的私钥。 + +:: + + $ ssh-add -d ~/.ssh/github_rsa + Identity removed: /Users/jiangxin/.ssh/github_rsa (/Users/jiangxin/.ssh/github_rsa.pub) + +hub命令 +------------ + +iOS应用 +------------ + diff --git a/06-side-projects/070-opensource.rst b/06-side-projects/070-opensource.rst new file mode 100644 index 0000000..496482c --- /dev/null +++ b/06-side-projects/070-opensource.rst @@ -0,0 +1,24 @@ +GitHub开源项目 +=============== + +Grit和ruby-git +--------------- + +Gollum +--------------- + +Jekyll +--------------- + +Resque +--------------- + +GitHub-servics +--------------- + +API +--------------- + +rubygems +--------------- + diff --git a/06-side-projects/gist.rst b/06-side-projects/gist.rst deleted file mode 100644 index 65184b8..0000000 --- a/06-side-projects/gist.rst +++ /dev/null @@ -1,280 +0,0 @@ -.. _gist: - -GitHub:Gist -=============== -在GitHub网站的导航条上就有Gist子网站的链接: https://gist.github.com/ ,\ -在本节我们就揭开其面纱。 - -.. figure:: /images/side-projects/gist-in-github-navbar.png - :scale: 100 - - 图6-1:GitHub上的Gist链接 - -Gist作为一个粘贴数据的工具,就像 Pastie 网站\ [#]_\ 一样,可以很容易地将数据\ -粘贴在Gist网站中,并在其他网页中引用Gist中粘贴的数据。作为GitHub的一个子网站,\ -很自然地,Gist使用Git版本库对粘贴数据进行维护,这非常酷。 - -.. _paste: - -数据的粘贴和引用 ------------------ -进入Gist网站的首页,就会看到一个大大的数据粘贴对话框,如图6-2所示。 - -.. figure:: /images/side-projects/gist-homepage.png - :scale: 100 - - 图6-2:Gist网站首页 - -只要提供一行简单的描述、文件名,并粘贴文件内容,即可创建一个新的粘贴。创建\ -新的粘贴时,如果不指定文件名,将由系统自动指派。如图6-3所示。 - -.. figure:: /images/side-projects/gist-create-new.png - :scale: 100 - - 图6-3:创建新的Gist - -每一个新的粘贴称为一个Gist,并拥有唯一的URL。如果选择创建公开的Gist,URL中将\ -使用顺序递增的ID号,如本例创建的Gist的URL地址为:\ -https://gist.github.com/1202870\ 。 - -若选择创建私有Gist,URL中则采用20位十六进制数字的ID,例如私密Gist:\ -https://gist.github.com/78d67164131ec9e08dfe\ 。需要指出的是,私有Gist的\ -私密性并不像GitHub私有版本库的私密性那么强,只是其URL没有在用户Gist列表中列出,\ -也不能通过Gist网站搜索到而已。如果用户知道某私密Gist的URL地址,同样可以访问、\ -克隆该私密Gist,甚至创建基于该Gist创建分支(fork)。 - -当一个粘贴创建完毕后,会显示新建立的Gist页面,如图6-4所示。 - -.. figure:: /images/side-projects/gist-created.png - :scale: 100 - - 图6-4:新创建的Gist - -点击其中的“embed”(嵌入)按钮,就会显示一段用于嵌入其他网页的JavaScript代码,\ -如图6-5所示。 - -.. figure:: /images/side-projects/gist-embed.png - :scale: 100 - - 图6-5:显示嵌入Java - - -对应的嵌入JavaScript代码如下: - -:: - - - - -将上面的JavaScript代码嵌入到网页(如博客\ [#]_\ )中,即可在相应的网页中嵌入\ -来自Gist的数据,并保持语法加亮等功能,如图6-6所示。 - -.. figure:: /images/side-projects/gist-embed-in-blog.png - :scale: 100 - - 图6-6:博客中引用Gist数据 - -.. _git-backend-gist: - -Gist背后的Git库 ------------------ -创建的每一个Gist的背后都对应着一个Git版本库。例如之前创建的ID为1202870的Gist\ -对应的Git版本库,可以使用两种协议进行访问: - -* Git协议:\ ``git://gist.github.com/1202870.git`` -* SSH协议:\ ``git@gist.github.com:1202870.git`` - -可以通过Git命令克隆和操作该版本库。 - -* 克隆该Gist对应的版本库。 - - :: - - $ git clone git@gist.github.com:1202870.git - $ cd 1202870 - -* 查看修改日志。每一次对Gist中文件的修改对应于一次提交。 - - :: - - $ git log - commit 993d28a1319eca314ab2e3f4c46882cf328e5ff9 - Author: GotGitHub - Date: Thu Sep 15 15:41:10 2011 +0800 - - commit 4dd9cfd54e1522d0b62d92dd5f705a61e3fe8778 - Author: GotGitHub - Date: Thu Sep 8 00:46:50 2011 -0700 - - -* 查看最近一次更改。 - - :: - - $ git show HEAD - commit 993d28a1319eca314ab2e3f4c46882cf328e5ff9 - Author: GotGitHub - Date: Thu Sep 15 15:41:10 2011 +0800 - - diff --git a/countdown.rb b/countdown.rb - index a9d747b..9045738 100644 - --- a/countdown.rb - +++ b/countdown.rb - @@ -4,4 +4,8 @@ - require 'Date' - - days=(DateTime.new(2012,10,15)-DateTime.now).ceil - -puts "Maybe #{days} days left." - \ No newline at end of file - +if days >= 0 - + puts "Maybe #{days} days left." - +else - + puts "Passed for #{days.abs} days." - +end - \ No newline at end of file - -Gist网站并没有像GitHub网站那样对于Git版本库提供完整的、近乎复杂的操作界面和\ -工作流支持,而只提供了最基本的操作界面。如图6-7所示。 - -.. figure:: /images/side-projects/gist-git-repo.png - :scale: 100 - - 图6-7:Gist版本库简易操作界面 - -在这个简易的Git版本库操作界面中,左侧是版本库的简介、文件预览以及在线编辑、\ -下载、加注星标\ [#]_\ 、版本库分支\ [#]_\ 等相关操作按钮。若以Gist创建者登录,\ -会在右侧看到他人基于该Gist创建分支的情况,但是并不提供GitHub才有的Pull Request\ -等功能。在界面的右侧还显示了Gist修订历史,和之前通过\ ``git log``\ 命令\ -从Git版本库看到的一样。 - -.. _greasemonkey: - -Greasemonkey ------------------ -Gist除了被用于粘贴数据(如代码块)并在网页中引用之外,还被用户挖掘出了新的\ -应用模式,例如用作Greasemonkey脚本的维护\ [#]_\ 。 - -Greasemonkey\ [#]_\ 或类似插件为浏览器提供用户端JavaScript扩展功能,最早\ -出现于FireFox浏览器中。其他浏览器也陆续增加了对用户端JavaScript的支持,\ -如Safari的 NinjaKit\ [#]_\ 插件,IE的Trixie\ [#]_\ 插件,以及Chrome的\ -Greasemetal插件\ [#]_\ 。关于如何在浏览器中安装并启用相应的插件,参照相关\ -插件网站的介绍,在此不做过多叙述。 - -当浏览器安装了 Greasemonkey 或类似插件之后,当访问扩展名为\ ``.user.js``\ -的URL时,会将该URL指向的JavaScript脚本安装在浏览器中,当访问指定的网址时会\ -自动调用相应的JavaScript脚本,修改相关网页内容或添加特效等等。 - -我针对《Git权威指南》官网的测试网页写了一个Greasemonkey示例脚本,可以展示\ -用户端JavaScript的魔法,这个用户端JavaScript脚本保存在Gist中:\ -https://gist.github.com/1084591\ ,如图6-8所示。 - -.. figure:: /images/side-projects/gist-greasemonkey.png - :scale: 100 - - 图6-8:保存Greasemonkey用户端脚本的Gist - -该Greasemonkey脚本的文件名为\ ``click_more.user.js``\ ,该文件的文件头使用\ -特殊的注释语句为Greasemonkey提供相关的安装和注册信息,内容如下(为方便描述\ -添加了行号): - -:: - - 1 // ==UserScript== - 2 // @name Click more for toggle - 3 // @namespace gotgit - 4 // @description Add a toogle effect at the location where anchor with a click-more css. - 5 // @include http://www.worldhello.net/gotgit/demo* - 6 // @include http://gotgit.github.com/gotgit/demo* - 7 // @include http://www.ossxp.com/doc/gotgit/demo* - 8 // @require http://code.jquery.com/jquery-1.6.2.min.js - 9 // ==/UserScript== - -其中第5、6、7行三条\ `include`\ 语句限定了此用户端JavaScript脚本的应用范围,\ -即只针对指定的URL(使用通配符)执行该脚本。第8行设定脚本依赖,即该脚本依赖\ -jQuery,会在运行前到指定的URL地址加载jQuery脚本。 - -在安装该脚本前,先用浏览器访问网址\ http://www.worldhello.net/gotgit/demo.html\ ,\ -看看不加载用户端JavaScript脚本时网页的模样。该网页中包含一个长长的网上书店\ -列表,如图6-9所示。 - -.. figure:: /images/side-projects/gist-user-js-apply-before.png - :scale: 100 - - 图6-9:应用用户端JavaScript脚本前的网页内容 - -接下来开始安装该用户端JavaScript脚本。安装非常简单,只要点击图6-8的Gist当中\ -的脚本文件对应的“raw”链接,即点击脚本文件原始内容链接\ [#]_\ 即可开启安装。\ -这是因为该URL以\ ``.user.js``\ 结尾,会被Greasemonkey(或类似插件)识别并安装,\ -如图6-10是Greasemonkey弹出的用户端脚本安装界面。 - -.. figure:: /images/side-projects/gist-user-js-install.png - :scale: 100 - - 图6-10:安装用户端JavaScript脚本 - -用户端脚本安装完毕后,再访问同样的测试网页\ -http://www.worldhello.net/gotgit/demo.html\ ,会发现网页中出现了\ -一个名为“更多”的可点击链接,长长的网上书店列表不见了。如图6-11所示。 - -.. figure:: /images/side-projects/gist-user-js-apply-after.png - :scale: 100 - - 图6-11:应用用户端JavaScript脚本后的网页内容 - -如果查看网页源码,会发现该网页中根本没有包含和调用任何JavaScript脚本,只是\ -在页面源码中包含着一个没有任何实质输出的标签: - -:: - -

- -实际上正是这个特殊的标签被Greasemonkey所加载的用户端脚本识别,为HTML网页\ -添加了特效。 - -.. _gist-cli: - -命令行操作Gist ------------------ -GitHub开发者还写了一个名为gist的命令行工具对Gist进行操作,地址见\ -https://github.com/defunkt/gist\ 。 - -该工具使用Ruby开发,对两个特定的Git风格的配置变量进行如下设置后,即可实现在\ -命令行中自动以特定用户身份登录操作Gist。 - -:: - - $ git config --global github.user "your-github-username" - $ git config --global github.token "your-github-token" - -其中\ ``github.token``\ 中保存的是用户的API TOKEN,这在“2.1 创建GitHub账号”\ -一节有过介绍。 - -使用gist命令行工具创建新的Gist非常简单。 - -* 创建包含一个文件(如\ ``script.py``\ )的Gist,使用如下命令。 - - :: - - $ gist script.py - -* 创建包含多个文件的Gist,使用类似如下的命令。 - - :: - - $ gist script.js notes.txt - -如果对命令行操作方式感兴趣,参考gist工具网站的\ `README`\ 文件。 - - ----- - -.. [#] http://pastie.org/ -.. [#] http://www.worldhello.net/2011/09/14/2521.html -.. [#] 对感兴趣的Gist进行收藏,参见博客 https://github.com/blog/673-starring-gists 。 -.. [#] 访问他人创建的Gist时,提供分支功能按钮。 -.. [#] https://github.com/blog/302-gist-for-greasemonkey -.. [#] https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/ -.. [#] http://ss-o.net/safari/extension/NinjaKit.safariextz -.. [#] http://www.bhelpuri.net/Trixie/ -.. [#] 版本4之后的Chrome内置了Greasemonkey类似功能,无需额外插件。 -.. [#] https://gist.github.com/raw/1084591/73c3e4dfc827732241ca753fe7bb985c14c9d7ab/click_more.user.js diff --git a/06-side-projects/github-mac.rst b/06-side-projects/github-mac.rst deleted file mode 100644 index 5bfbf14..0000000 --- a/06-side-projects/github-mac.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _mac: - -github:mac ------------------------ - -GitHub专为Mac用户开发了一款图形化客户端应用\ ``github:mac``\ ,在Mac下操作\ -GitHub更简单。软件下载地址: http://mac.github.com/ 。 - -``github:mac`` 可以实现版本库克隆、查看历史、提交、分支管理、与GitHub同步等\ -功能。图6-12展示的是提交界面,在提交界面中同时显示了变更的差异比较,用户可以\ -挑选文件中的部分变更进行提交,显然这个操作要比在命令行中执行\ -:command:`git add --patch`\ 或\ :command:`git commit --patch`\ 要更加直观。 - -.. figure:: /images/side-projects/mac-partial-commit.png - :scale: 100 - - 图6-12:筛选文件中的部分更改进行提交 - -``github:mac``\ 和GitHub深度集成,当配置好关联的GitHub账号后,会自动在本地\ -创建专用的SSH公钥/私钥对文件 :file:`~/.ssh/github_rsa` (如果该文件不存在的\ -话),然后将公钥文件传递到GitHub网站并自动完成配置。新增的SSH公钥文件显示在\ -GitHub网站的账号设置中,如图6-13所示: - -.. figure:: /images/side-projects/mac-new-ssh-pubkey.png - :scale: 100 - - 图6-13:在GitHub上自动添加的SSH公钥 - -同时\ ``github:mac``\ 还在本地将新生成的私钥文件添加到\ ``ssh-agent``\ -认证代理中,这样一旦通过 SSH 协议连接GitHub,首先采用该公钥/私钥对进行身份\ -认证。用下面的命令可以查看添加到\ ``ssh-agent``\ 中的私钥文件。 - -:: - - $ ssh-add -l - 2048 aa:01:4f:d2:14:ba:5f:9f:8c:dc:b5:9d:44:cd:8e:18 /Users/jiangxin/.ssh/github_rsa (RSA) - -这种透明的公钥认证管理非常酷,对于大多数只使用唯一一个GitHub账号的用户来说\ -是非常方便的。但如果用户拥有多个GitHub账号并需要不时切换账号,这种实现却很\ -糟糕,会导致认证错误。因为当\ ``ssh-agent``\ 认证代理缓存了私钥后,连接由\ -文件 :file:`~/.ssh/config` 设置的 SSH 别名主机无法使用指定的公钥/私钥对进行\ -认证,导致认证失败。 - -遇到 GitHub 账户 SSH 认证问题,可以运行下面命令清空\ ``ssh-agent``\ 缓存的私钥。 - -:: - - $ ssh-add -d ~/.ssh/github_rsa - Identity removed: /Users/jiangxin/.ssh/github_rsa (/Users/jiangxin/.ssh/github_rsa.pub) diff --git a/06-side-projects/hub.rst b/06-side-projects/hub.rst deleted file mode 100644 index 8729ea1..0000000 --- a/06-side-projects/hub.rst +++ /dev/null @@ -1,207 +0,0 @@ -.. _hub: - -hub ------------- - -对于命令行用户,GitHub提供了名为\ ``hub``\ 的命令行工具,对Git进行了简单的\ -封装。该项目在GitHub上的地址为: https://github.com/defunkt/hub 。 - -使用\ ``hub``\ 可以在命令行中简化对GitHub的操作。例如克隆本电子书的版本库,\ -若用\ ``hub``\ 命令,地址可大大简化: - -:: - - $ hub clone gotgit/gotgithub - -若要在自己账号下创建派生项目,无需登录GitHub网站,直接通过命令行即可实现: - -:: - - $ cd gotgithub - $ hub fork - -安装\ ``hub``\ 很简单,可使用如下方法任意一种方法。 - -* 克隆\ ``hub``\ 的版本库,从源码安装。安装步骤如下: - - :: - - $ git clone git://github.com/defunkt/hub.git - $ cd hub - $ rake install prefix=/usr/local - -* 用 RubyGems 包方式安装。 - - ``hub``\ 用 Ruby 开发,也可用 RubyGems 包方式安装。需要注意,在安装完毕后\ - 最好将\ ``hub``\ 打包为一独立运行脚本,以便运行时不再靠 RubyGems 加载,\ - 提高加载速度。安装步骤如下: - - :: - - $ gem install hub - $ hub hub standalone > ~/bin/hub && chmod 755 ~/bin/hub - -安装完毕后,还需要对\ ``hub``\ 进行设置。定义两个Git风格的配置变量,以便\ -``hub``\ 命令能确定当前GitHub用户账号,并能够完成所需的 GitHub API 认证。 - -:: - - $ git config --global github.user "your-github-username" - $ git config --global github.token "your-github-token" - -其中\ ``github.token``\ 中保存的是用户的API TOKEN,这在“2.1 创建GitHub账号”\ -一节有过介绍。 - -在使用\ ``hub``\ 过程中,如果要为区分哪些命令是\ ``git``\ 的,哪些是\ ``hub``\ -的,而不断在两个命令间切换显然太不方便了。``hub`` 命令支持以系统别名\ ``git``\ -的方式运行,即设置\ ``hub``\ 的系统别名为\ ``git``\ ,然后只需执行\ ``git``\ -命令,这样无论是\ ``git``\ 本身的命令还是\ ``hub``\ 扩展的命令都可正常运行。\ -但要注意要用系统提供的别名方式,而不能把\ ``hub``\ 脚本改名为\ ``git``\ ,\ -因为\ ``hub``\ 只是简单地对Git进行封装,运行时仍依赖\ ``git``\ 命令。在 bash \ -环境下建立别名可运行如下命令: - -:: - - $ alias git=hub - -其他 shell 环境下如何建立系统别名呢?运行\ ``hub alias ``\ 命令查看\ -相关 shell 环境下建立别名的方法。例如对于 csh: - -:: - - $ hub alias csh - Run this in your shell to start using `hub` as `git`: - alias git hub - -下面介绍\ ``hub``\ 的常用命令,节选自\ ``hub``\ 的项目页\ [#]_\ 。示例使用\ -了别名命令\ ``git``\ 调用,并把对应的原始的\ ``git``\ 命令写在命令的下面\ -(用提示符\ ``>``\ 表示,方括号中是说明)。 - -* git create - - 在GitHub上创建项目。 - - :: - - $ git create -d '项目表述' - > [ 在GitHub上创建版本库 ] - > git remote add origin git@github.com:YOUR_USER/CURRENT_REPO.git - - $ git create recipes - > [ 在GitHub上创建版本库 ] - > git remote add origin git@github.com:YOUR_USER/recipes.git - - $ git create sinatra/recipes - > [ 在组织账号 sinatra 下创建版本库 ] - > git remote add origin git@github.com:sinatra/recipes.git - -* git clone - - 克隆版本库可使用URL简写,即“用户名/版本库”格式地址会自动扩展为Git协议\ - (只读)地址或SSH协议(可写)地址。 - - :: - - $ git clone schacon/ticgit - > git clone git://github.com/schacon/ticgit.git - - $ git clone -p schacon/ticgit - > git clone git@github.com:schacon/ticgit.git - - $ git clone resque - > git clone git@github.com/YOUR_USER/resque.git - -* git fork - - 在GitHub自己账号下建立派生项目。 - - :: - - $ git fork - > [ 先在GitHub 上建立派生项目 ] - > git remote add -f YOUR_USER git@github.com:YOUR_USER/CURRENT_REPO.git - -* git pull-request - - 打开编辑器输入标题和内容,然后在 GitHub 上创建 Pull Request。 - - -* git remote add - - 设置远程版本库。和\ ``git clone``\ 命令一样支持URL简写。 - - :: - - $ git remote add rtomayko - > git remote add rtomayko git://github.com/rtomayko/CURRENT_REPO.git - - $ git remote add -p rtomayko - > git remote add rtomayko git@github.com:rtomayko/CURRENT_REPO.git - - $ git remote add origin - > git remote add origin git://github.com/YOUR_USER/CURRENT_REPO.git - -* git fetch - - 获取他人同名版本库。自动建立远程版本库并获取提交。 - - :: - - $ git fetch mislav - > git remote add mislav git://github.com/mislav/REPO.git - > git fetch mislav - - $ git fetch mislav,xoebus - > git remote add mislav ... - > git remote add xoebus ... - > git fetch --multiple mislav xoebus - -* git cherry-pick - - 获取远程提交,并拣选至本地版本库。 - - :: - - $ git cherry-pick http://github.com/mislav/REPO/commit/SHA - > git remote add -f mislav git://github.com/mislav/REPO.git - > git cherry-pick SHA - -* git am, git apply - - 获取 Pull Request,并应用于本地版本库。 - - :: - - $ git am https://github.com/defunkt/hub/pull/55 - > curl https://github.com/defunkt/hub/pull/55.patch -o /tmp/55.patch - > git am /tmp/55.patch - -* git browse - - 打开浏览器访问相应的URL地址。 - - :: - - $ git browse - > open https://github.com/YOUR_USER/CURRENT_REPO - - $ git browse -- commit/SHA - > open https://github.com/YOUR_USER/CURRENT_REPO/commit/SHA - - $ git browse -- issues - > open https://github.com/YOUR_USER/CURRENT_REPO/issues - - $ git browse resque - > open https://github.com/YOUR_USER/resque - - $ git browse schacon/ticgit - > open https://github.com/schacon/ticgit - - $ git browse schacon/ticgit commit/SHA - > open https://github.com/schacon/ticgit/commit/SHA - -* git help hub - - 查看\ ``hub``\ 命令的帮助。 - -.. [#] https://github.com/defunkt/hub#readme diff --git a/06-side-projects/index.rst b/06-side-projects/index.rst index 7240830..960f3bc 100644 --- a/06-side-projects/index.rst +++ b/06-side-projects/index.rst @@ -1,16 +1,14 @@ -.. _by-products: - GitHub副产品 ******************** -GitHub最核心的产品是Git版本库(即项目)托管,此外GitHub还提供一些副产品\ -(Side Project),通过附加的服务或技术提供了更多有趣的功能。例如提供数据粘贴的\ -Gist网站,对其他版本控制工具如SVN和Hg的支持,各具特色的客户端工具,求职网站,\ -销售纪念品的GitHub商店等等。 +GitHub最核心的产品是Git版本库(即项目)托管,此外GitHub还通过一些附加的服务或技术提供了更多有趣的功能。例如提供数据粘贴的Gist网站,求职网站,销售纪念品的GitHub商店,供SVN和Hg用户访问Git版本库的技术等等。 .. toctree:: :maxdepth: 1 - gist - other-scm - tools - others + 010-gist + 020-jobs + 030-shop + 040-svn + 050-hg-git + 060-client-tools + 070-opensource diff --git a/06-side-projects/ios.rst b/06-side-projects/ios.rst deleted file mode 100644 index 265e6f6..0000000 --- a/06-side-projects/ios.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _ios: - -iOS应用 ------------- - -GitHub还为iOS平台开发了应用,这样就可以在 iPhone、iPad 等苹果设备上实时跟踪\ -GitHub上的项目了。在苹果AppStore上搜索GitHub公司的应用,可以找到GitHub Issues\ -和GitHub Jobs等应用,如图6-14所示。 - -.. figure:: /images/side-projects/ios-apps.png - :scale: 100 - - 图6-14:iPhone上的issues应用 - -在iPhone中安装GitHub Issues应用,就可以随时查看所关注的GitHub项目的问题报告\ -和Pull Request等,如图6-15所示。 - -.. figure:: /images/side-projects/ios-issues-iphone.png - :width: 300 - - 图6-15:iPhone上的GitHub Issues应用 - -而GitHub Jobs应用则和即将要介绍的GitHub招聘网站有关,用于浏览招聘信息。 diff --git a/06-side-projects/jobs.rst b/06-side-projects/jobs.rst deleted file mode 100644 index abdbc41..0000000 --- a/06-side-projects/jobs.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _jobs: - -GitHub:Jobs -=============== -GitHub求职网站\ [#]_\ ,于2010年8月开通,提供求职招聘服务\ [#]_\ 。还记得在\ -“第2.1节 创建GitHub账号”介绍的相关内容么?当用户在个人设置中对简历和求职状态\ -进行设置和启用后,GitHub就会帮助用户寻找合适的工作机会,而工作机会就来自于\ -GitHub的求职网站(如图6-16所示)。 - -.. figure:: /images/side-projects/jobs-homepage.png - :scale: 100 - - 图6-16:GitHub求职网站 - -个人用户除了开启求职状态坐等通知外,还可以主动出击,直接到GitHub求职网站上\ -寻找合适的工作机会,整个求职过程是免费的。而作为企业主发布招聘启示则是收费\ -服务,发布招聘启示的流程如图6-17所示。 - -.. figure:: /images/side-projects/jobs-post-process.png - :scale: 100 - - 图6-17:企业主发布招聘启示流程 - -企业发布招聘启示,首先要按照模版填写职位说明及留下供求职者投递简历的邮件地址,\ -然后用信用卡付费,每一个招聘启示的付费标准为350美元/月。一旦付费完成招聘马上\ -生效。GitHub作为程序员的聚集地,无疑是招聘和应聘的理想之地。 - ----- - -.. [#] http://jobs.github.com/ -.. [#] https://github.com/blog/694-github-jobs-launches-tomorrow diff --git a/06-side-projects/opensource.rst b/06-side-projects/opensource.rst deleted file mode 100644 index 17d2587..0000000 --- a/06-side-projects/opensource.rst +++ /dev/null @@ -1,172 +0,0 @@ -_github-opensource: - -GitHub Open Source -=================== - -GitHub已成为新的开源项目大本营,而且GitHub也将其API开放,并将部分模块开源,\ -借助社区的力量让GitHub变得更好。 - -GitHub大部分的开源项目托管在其官方账号下: https://github.com/github 。 - -.. _api: - -API接口 -------- -GitHub通过域名\ ``api.github.com``\ 提供API接口,数据以JSON格式传递。 - -详细的API参考手册参见网址: http://developer.github.com/ 。API手册的版本库\ -地址: https://github.com/github/developer.github.com 。 - -.. _help-project: - -官方手册 --------- -GitHub官方手册参见 http://help.github.com/ ,使用 Jekyll 维护。 - -项目地址: https://github.com/github/help.github.com 。 - -.. _grit: - -Grit ----- -Grit是Git的Ruby封装和实现,是GitHub调用Git的接口。部分是通过封装对\ ``git``\ -命令的调用实现的,部分则是纯Ruby实现。 - -项目地址: https://github.com/mojombo/grit 。 - -.. _services-project: - -GitHub Services ---------------- -Git版本库推送会触发服务器端\ ``post-receive``\ 钩子脚本。此项目将GitHub的\ -服务器端钩子脚本开源,用户可以开发针对特定应用的钩子。GitHub还为其他GitHub\ -应用提供了事件接口,如问题变更、Pull Request、维基页面修改等\ [#]_\ 。 - -项目地址: https://github.com/github/github-services 。 - -.. _hobot: - -Hubot 和 Hubot Scripts ----------------------- -可以把 hubot\ [#]_\ 看做是GitHub的Siri(最早出现于iPhone 4S 的智能语音助理)\ -或是新浪微博上的饮水姬\ [#]_\ 。GitHub将hobot和Campfire聊天室整合,\ -hobot被聊天室会话触发可以实现诸如:打开办公室的门、根据wifi使用情况列出公司中的人、\ -通过公司喇叭读一段信息等等许多好玩的事情\ [#]_\ ,而实现GitHub自动化部署\ -则证明 hubot 可以完成更严肃的事情,在公司工作流中扮演举足轻重的地位\ [#]_\ 。 - -Hobot已经开源,项目库地址:\ https://github.com/github/hubot\ 和\ -https://github.com/github/hubot-scripts\ (脚本)。 - -.. _gollum: - -Gollum ------- -GitHub以Git为后端的维基系统就是由Gollum实现的。每一个维基网页对应于一个文件,\ -文件格式可以是 Markdown、textile、rdoc、org、creole、mediawiki、\ -reStructuredText、asciidoc、pod 等。Gollum 调用名为github-markup的Ruby gem包\ -(来自于下面要介绍的 Markup 项目)完成文件到网页的格式转换。 - -项目地址: https://github.com/github/gollum 。 - -关于GitHub维基参见本书“第4.6节维基”。 - -.. _jekyll-project: - -Jekyll ------- -Jekyll 是一个简单的、支持博客的静态网站编译器。可以使用Markdown和Textile两种\ -标记语言或者HTML撰写网页,并支持Liquid模版。实际上GitHub为托管项目生成静态\ -网页使用的就是Jekyll。 - -项目地址: https://github.com/mojombo/jekyll 。 - -.. _linguist: - -Linguist --------- -Linguist 是一个Ruby模块,GitHub使用该模块对数据文件进行语义分析,检测文件的\ -语言种类,代码加亮,对二进制文件进行忽略,限制非必须的差异显示,以及生成语言\ -分类图等。 - -项目地址: https://github.com/github/linguist 。 - -.. _markup: - -Markup ------- -GitHub通过这个ruby包对项目版本库根目录下的\ ``README``\ 文件,以及维基页面\ -等文件进行解析、转换为网页显示。支持 Markdown、textile、rdoc、org、creole、\ -mediawiki、reStructuredText、asciidoc、pod 等标记语言。实际上在对上述标记语言\ -的解析和转换中,还依赖其他软件包,例如对于 Markdown 格式首选 Redcarpet\ [#]_\ ,\ -对 textile 格式使用 RedCloth,对 reStructuredText 格式调用外部命令\ -``rst2html``\ ,对 asciidoc 格式调用外部命令\ ``asciidoc``\ 等。 - -项目地址: https://github.com/github/markup 。 - -关于Markup软件包以及其他GitHub扩展的Markdown语法,参见:\ -http://github.github.com/github-flavored-markdown\ 。 - -.. _resque: - -Resque ------- -Resque(发音类似 "rescue")是一个以Redis为后端的Ruby包,用于创建和管理后台\ -任务。可创建任务,将任务分配到多个队列,并在后台执行任务。 - -项目地址: https://github.com/defunkt/resque 。 - -.. _gitpad: - -GitPad ------- -这是一个运行于Windows下类似\ ``Notepad.exe``\ 的应用程序,安装此应用后在\ -Windows下做Git提交操作会调用类似记事本(Notepad)的应用撰写提交说明。 - -项目地址: https://github.com/github/GitPad 。 - -.. _maven-plugins: - -Maven Plugins -------------- -GitHub的Maven插件。 - -项目地址: https://github.com/github/maven-plugins 。 - -.. _gitignore: - -Gitignore ---------- -集合了针对各种语言环境的\ ``.gitignore``\ (忽略文件)模版。例如其中针对\ -VisualStudio的忽略文件模版\ ``Global/VisualStudio.gitignore``\ 部分内容如下: - -:: - - # User-specific files - *.suo - *.user - *.sln.docstates - - # Build results - [Dd]ebug/ - [Rr]elease/ - -项目地址: https://github.com/github/gitignore 。 - -.. _media-project: - -Media -------- -提供GitHub网站Logo和吉祥物 Octocat 的图片,只能在授权范围内使用。 - -项目地址: https://github.com/github/media 。 - - ----- - -.. [#] https://github.com/blog/964-all-of-the-hooks -.. [#] http://hubot.github.com/ -.. [#] http://weibo.com/u/2625288792 -.. [#] http://zachholman.com/posts/why-github-hacks-on-side-projects/ -.. [#] http://scottchacon.com/2011/08/31/github-flow.html#6__deploy_immediately_after_review -.. [#] Redcarpet 是对一个高效的Markdown解析器,通过对C语言的 Sundown 库封装实现。\ - 项目地址:\ https://github.com/tanoku/redcarpet\ 。 diff --git a/06-side-projects/other-scm.rst b/06-side-projects/other-scm.rst deleted file mode 100644 index a235a6a..0000000 --- a/06-side-projects/other-scm.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _other-scm-support: - -其他版本控制工具支持 -======================= - -如果曾经有人对 GitHub 只提供唯一的版本库格式(Git)托管表示过怀疑的话,那么\ -今天看到 GitHub 对其他版本控制工具提供的愈发完善的支持,争议应该烟消云散了吧。 - -.. toctree:: - :maxdepth: 1 - - svn - hg-git diff --git a/06-side-projects/others.rst b/06-side-projects/others.rst deleted file mode 100644 index 815fb96..0000000 --- a/06-side-projects/others.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _others: - -其他 -====== - - -.. toctree:: - :maxdepth: 1 - - jobs - shop - short-url - opensource diff --git a/06-side-projects/shop.rst b/06-side-projects/shop.rst deleted file mode 100644 index 0d60718..0000000 --- a/06-side-projects/shop.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _shop: - -GitHub:Shop -=============== -GitHub商店\ [#]_\ 销售着一些你在其他地方买不到的小东西——如印着GitHub吉祥物\ -Octocat的纪念品,图6-18展示的就是一款印着Octocat的杯子。 - -.. figure:: /images/side-projects/shop-octocat-mug.jpg - :scale: 100 - - 图6-18:印着Octocat吉祥物的杯子 - -图6-19则是GitHub热卖的一款体恤的前后两面的图案设计\ [#]_\ 。体恤前面印着GitHub\ -社区编程最核心的理念(fork you),体恤后面则可以用记号笔写下你在GitHub上的\ -主页地址。 - -.. figure:: /images/side-projects/shop-fork-you-shirt.png - :scale: 100 - - 图6-19:超酷的GitHub体恤 - -GitHub商店实际上是架设于Shopify\ [#]_\ 电子商务网站上的网店。GitHub商店并非\ -GitHub主业,销售纪念品可以增强GitHub用户的认同感,而GitHub粉丝可以购买一项\ -“装备”让自己看起来更酷。 - ----- - -.. [#] http://shop.github.com/ -.. [#] https://github.com/blog/676-fork-you -.. [#] http://www.shopify.com/ diff --git a/06-side-projects/short-url.rst b/06-side-projects/short-url.rst deleted file mode 100644 index bf2315b..0000000 --- a/06-side-projects/short-url.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _short-url: - -GitHub短网址服务 -=================== - -在“第2.2节 浏览托管项目”一节介绍图形文件差异比较时,需要给出一个网址,但\ -这个网址很长。如下: - -:: - - https://github.com/cameronmcefee/Image-Diff-View-Modes/commit/8e95f70c9c47168305970e91021072673d7cdad8 - -很自然地想到了Google短网址服务,于是由上面的长网址生成出一个短小精干的网址:\ -http://goo.gl/Gy85b\ ,访问该短网址会自动重定向到对应的长网址。 - -2011年11月,GitHub也推出了自己的短网址服务\ [#]_\ ,为GitHub自身网址提供\ -短网址转换服务。GitHub短网址服务没有像Google短网址服务那样提供基于Web的图形\ -化转换界面,而是需要用命令行进行网址转换。 - -例如对于网址 https://github.com/blog/985-git-io-github-url-shortener 的转换,\ -使用\ ``curl``\ 命令如下操作。 - -* 将长网址转换为短网址。 - - 命令\ ``curl``\ 输出中的\ ``Location:``\ 语句即是转换后的短网址。 - - :: - - $ curl -i http://git.io -F 'url=https://github.com/blog/985-git-io-github-url-shortener' - ... - HTTP/1.1 201 Created - ... - Location: http://git.io/help - -* 查看短网址对应的原网址,同样使用\ ``curl``\ 命令。 - - 命令\ ``curl``\ 输出302重定向地址即为原始网址。 - - :: - - $ curl -i http://git.io/help - HTTP/1.1 302 Found - ... - Location: https://github.com/blog/985-git-io-github-url-shortener - -为使转换的短网址更易于记忆和识别,可在\ ``curl``\ 命令中用 code 参数设定期望的\ -短网址。例如下面命令将本节一开始提到的长网址转换为短网址:\ -http://git.io/image-diff\ 。 - -:: - - $ curl -i http://git.io -F \ - 'url=https://github.com/cameronmcefee/Image-Diff-View-Modes/commit/8e95f70c9c47168305970e91021072673d7cdad8' \ - -F 'code=image-diff' - ... - HTTP/1.1 201 Created - ... - Location: http://git.io/image-diff - - -.. [#] http://git.io/help diff --git a/06-side-projects/tools.rst b/06-side-projects/tools.rst deleted file mode 100644 index 72dad61..0000000 --- a/06-side-projects/tools.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _client-tools: - -客户端工具 -=============== - -GitHub提供的Web服务,在客户端通常只需要浏览器及Git命令行工具就可以满足需要了。\ -而GitHub还开发了一些客户端工具,以便用户有更好的客户端体验。 - -.. toctree:: - :maxdepth: 1 - - github-mac - hub - ios diff --git a/20-appendix/010-markup-markdown.rst b/20-appendix/010-markup-markdown.rst new file mode 100644 index 0000000..b4689a5 --- /dev/null +++ b/20-appendix/010-markup-markdown.rst @@ -0,0 +1,3 @@ +Markdown +=================== + diff --git a/20-appendix/020-markup-textile.rst b/20-appendix/020-markup-textile.rst new file mode 100644 index 0000000..30657ec --- /dev/null +++ b/20-appendix/020-markup-textile.rst @@ -0,0 +1,3 @@ +Textile +=================== + diff --git a/20-appendix/030-markup-rdoc.rst b/20-appendix/030-markup-rdoc.rst new file mode 100644 index 0000000..09e0faa --- /dev/null +++ b/20-appendix/030-markup-rdoc.rst @@ -0,0 +1,3 @@ +RDoc +=================== + diff --git a/20-appendix/040-markup-org.rst b/20-appendix/040-markup-org.rst new file mode 100644 index 0000000..c75f2f6 --- /dev/null +++ b/20-appendix/040-markup-org.rst @@ -0,0 +1,2 @@ +Org-mode +=================== diff --git a/20-appendix/050-markup-creole.rst b/20-appendix/050-markup-creole.rst new file mode 100644 index 0000000..0f0cb48 --- /dev/null +++ b/20-appendix/050-markup-creole.rst @@ -0,0 +1,2 @@ +Creole +=================== diff --git a/20-appendix/060-markup-mediawiki.rst b/20-appendix/060-markup-mediawiki.rst new file mode 100644 index 0000000..fa56393 --- /dev/null +++ b/20-appendix/060-markup-mediawiki.rst @@ -0,0 +1,3 @@ +MediaWiki +=================== + diff --git a/20-appendix/070-markup-rest.rst b/20-appendix/070-markup-rest.rst new file mode 100644 index 0000000..cba7b27 --- /dev/null +++ b/20-appendix/070-markup-rest.rst @@ -0,0 +1,2 @@ +reStructuredText +=================== diff --git a/20-appendix/080-markup-asciidoc.rst b/20-appendix/080-markup-asciidoc.rst new file mode 100644 index 0000000..4bc4079 --- /dev/null +++ b/20-appendix/080-markup-asciidoc.rst @@ -0,0 +1,3 @@ +AsciiDoc +=================== + diff --git a/20-appendix/090-markup-pod.rst b/20-appendix/090-markup-pod.rst new file mode 100644 index 0000000..a0ecfec --- /dev/null +++ b/20-appendix/090-markup-pod.rst @@ -0,0 +1,3 @@ +Pod +=================== + diff --git a/20-appendix/index.rst b/20-appendix/index.rst new file mode 100644 index 0000000..906fd79 --- /dev/null +++ b/20-appendix/index.rst @@ -0,0 +1,15 @@ +附录:GitHub支持的标记语言 +****************************** + +.. toctree:: + :maxdepth: 1 + + 010-markup-markdown + 020-markup-textile + 030-markup-rdoc + 040-markup-org + 050-markup-creole + 060-markup-mediawiki + 070-markup-rest + 080-markup-asciidoc + 090-markup-pod diff --git a/Makefile b/Makefile index 51f4079..09695f4 100644 --- a/Makefile +++ b/Makefile @@ -37,38 +37,38 @@ help: clean: -rm -rf $(BUILDDIR)/* -html: pre-build +html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." -dirhtml: pre-build +dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." -singlehtml: pre-build +singlehtml: $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." -pickle: pre-build +pickle: $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." -json: pre-build +json: $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." -htmlhelp: pre-build +htmlhelp: $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." -qthelp: pre-build +qthelp: $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ @@ -77,7 +77,7 @@ qthelp: pre-build @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/GotGitHub.qhc" -devhelp: pre-build +devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @@ -86,52 +86,46 @@ devhelp: pre-build @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/GotGitHub" @echo "# devhelp" -epub: pre-build +epub: $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." -latex: pre-build +latex: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." -latexpdf: pre-build +latexpdf: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." make -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." -text: pre-build +text: $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." -man: pre-build +man: $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." -changes: pre-build +changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." -linkcheck: pre-build +linkcheck: $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." gh-pages: clean html - @if ! git rev-parse refs/heads/gh-pages >/dev/null 2>&1 ; then \ - echo "Branch gh-pages not exists, forgot check it out?" >&2; \ - exit 1; \ - fi - @cp README.md _build/html/ - @echo '*' > _build/html/images/.gitignore @git add -f _build/html; \ tree=$$(git write-tree); \ newhtml=$$(git ls-tree $$tree:_build | grep "html$$" | awk '{print $$3;}') ; \ @@ -146,40 +140,7 @@ gh-pages: clean html fi; \ git rm --cached -r -q _build/html -gh-pages-shift: - @if ! git rev-parse refs/heads/gh-pages^ >/dev/null 2>&1 ; then \ - echo "Branch gh-pages not exists or only one commit, forgot check it out?" >&2; \ - exit 1; \ - fi - if git update-ref -m "shift from $$(git rev-parse refs/heads/gh-pages)" refs/heads/gh-pages $$(git rev-parse refs/heads/gh-pages^); then \ - echo "gh-pages branch shift to last commit."; \ - fi - - doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." - -pre-build: images update-version - -images: - @(cd graphics; \ - if test -f Rakefile; then \ - rake convert[../images,600]; \ - else \ - echo "ERROR: Submodule 'graphics' not found. Please init submodule using: " >&2; \ - echo "ERROR: git submodule init && git submodule update" >&2; \ - exit 1; \ - fi) - -update-version: - @sed -e "s##$$(git describe --dirty --always)#g" < _version.inc.in > _version.inc.tmp - @if diff -q _version.inc.tmp _version.inc >/dev/null 2>&1; then \ - rm _version.inc.tmp; \ - else \ - echo "_version.inc.in => _version.inc" ; \ - mv _version.inc.tmp _version.inc; \ - fi - -.PHONY : clean pre-build images gh-pages diff --git a/README.md b/README.md deleted file mode 100644 index b04f360..0000000 --- a/README.md +++ /dev/null @@ -1,97 +0,0 @@ -这是一本关于GitHub的书,在线阅读请访问: 。 - -动笔写GitHub不是因为我对其了解,恰恰是对其太不了解。在我写的 [《Git权威指南》][gotgit] 一书中,涉及到GitHub的只有区区三页纸,这显然回答不了读者对于GitHub的诸多疑问。 - -这本书采用Creative Commons协议发布,并托管在GitHub上,意味着您可以免费阅读并可以用GitHub特有的方式参与本书的维护。 - -## 如何离线阅读 - -项目 [gotgit/gotgithub](https://github.com/gotgit/gotgithub) 的版本库中的 ``gh-pages`` 分支保存着本书编译后的页面,意味着您只要下载版本库并检出 ``gh-pages`` 分支即可在本地浏览。 - -* 克隆版本库。 - - $ git clone git://github.com/gotgit/gotgithub.git - -* 检出 ``gh-pages`` 分支。 - - $ cd gotgithub - $ git checkout gh-pages - -* 用浏览器打开 ``index.html`` 即可离线阅读。 - -因分支 ``gh-pages`` 的提交历史可能会周期性删除或压缩合并,为避免执行 ``git pull`` 更新分支时造成困惑,请对本地版本库进行如下设置。 - - $ git config --add remote.origin.fetch +refs/heads/gh-pages:refs/heads/gh-pages - -## 如何编译 - -### 预备 - -* Python, docutils - - 本书使用 [reStructuredText](http://docutils.sourceforge.net/rst.html) 格式撰写,格式解析依赖 Python 和 docutils 包。 - -* Sphinx - - 用 [Sphinx](http://sphinx.pocoo.org/) 工具进行编译。编译前先确认已经安装 Python、docutils 及 sphinx。 - -* ImageMagick 及 Inkscape - - 本书图片矢量图采用 [Inkscape](http://inkscape.org/) 绘制,位图处理采用 [GIMP](http://www.gimp.org/) 。上述格式图片在网页显示需要格式转换,格式转换需用到 ImageMagick 和 Inkscape。 - -* Git - - 不解释。 - -### 克隆版本库(本书书稿及图片) - -本书用两个版本库维护: - -* 书稿版本库: - - https://github.com/gotgit/gotgithub/ - -* 图片版本库: - - https://github.com/gotgit/gotgithub-graphics/ - - -本书的图片版本库以子模组形式关联到书稿版本库,运行下面命令执行克隆: - -* 若尚未克隆书稿版本库,先克隆书稿版本库。 - - $ git clone git://github.com/gotgit/gotgithub.git - $ cd gotgithub - -* 默认检出 ``master`` 分支。如果当前非 ``master`` 分支,执行下面命令检出分支。 - - $ git checkout master - -* 通过子模组更新命令克隆子模组版本库(即保存图片的版本库)并检出。 - - $ git submodule init - $ git submodule update - -### 编译书稿 - -确保安装了 Sphinx、ImageMagick、Inkscape。编译本书使用命令: - - $ make html - -编译后的网页位于 ``_build/html`` 目录下。 - -更多的格式输出参见下面的命令输出: - - $ make - -## 如何贡献 - -请采用GitHub方式贡献。 - -* 创建派生项目。即 Fork。 -* 修改您觉得不满意的地方。修改后推送到您创建的分支版本库中。 -* 通过 GitHub 向我发送 Pull Request。 - -[gotgit]: http://www.worldhello.net/gotgit/ "Got Git" - --- 蒋鑫, diff --git a/preface.inc b/README.rst similarity index 53% rename from preface.inc rename to README.rst index 852463d..1dbb996 100644 --- a/preface.inc +++ b/README.rst @@ -1,19 +1,17 @@ 动笔写GitHub不是因为我对其了解,恰恰是对其太不了解。 在我的《Git权威指南》 [#]_ 一书中,涉及到GitHub的只有区区三页纸,这显然回答不了读者对于GitHub的诸多疑问。 -记得在《Git权威指南》刚刚完稿之际,机械工业出版社华章公司的杨福川编辑就鼓动我写一本关于GitHub的书,我用了好多理由推辞了。 +记得在《Git权威指南》刚刚完稿之际,机械工业出版社华章公司的杨福川编辑就鼓动我写一本GitHub的书,我用了好多理由推辞了。 头条理由就是我真的累着了。在每一章节开始动笔之时,都好像是坐在了中学语文考试的考堂上写作文,时间快到了可仍然动不了笔, 再写一本书无疑要重复这一痛苦的经历。 第二个理由是我更喜欢编程,而不是写文档,尤其写GitHub会有大量截图、图像处理的琐碎工作。 -第三个理由彻底让编辑投降,那就是GitHub是一个国外网站,也许书一出,【此句已被原作者删除】。 +第三个理由彻底让编辑投降,那就是GitHub是一个国外网站,也许书一出,网站却无法访问,理由吗,地球人都知道。 -让我最终决定动笔,是源于CSDN蒋总在美国拜访GitHub总部后告诉我的一些见闻,我对GitHub如此成功运作产生了兴趣,于是开始研究GitHub的博客,愈发发现GitHub是一群有趣的人在做的有趣的事,如果只把GitHub当作一个Git服务器,实在是暴殄天物。GitHub已经并将继续获得成功,若真能凭借此书把GitHub尽量全面地展现,让每一个Git使用者用好GitHub也是一件幸事。 +让我终于决定动笔,是源于CSDN蒋总在美国拜访GitHub总部后告诉我的一些信息,我对GitHub如此成功运作产生了兴趣,于是开始研究GitHub的博客,愈发发现GitHub是一群有趣的人在做的有趣的事,如果只把GitHub当做一个Git服务器,实在是暴殄天物。GitHub已经并将继续获得成功,若真能凭此书把GitHub尽量全面的展现,让每一个Git爱好者用好GitHub也是一件幸事。 -这本书将采用GitHub的方式进行撰写和发布 [#]_ ,任何人都可以看到本书(包括源码),更可以用GitHub的方法参与本书的撰写和纠错。网络出版对于我和杨福川编辑都是一个全新的体验。感谢Git,让我在一年内拥有了两种不同的出版体验。 - --- 蒋鑫, 2011.12 +这本书将采用GitHub的方式进行撰写和发布 [#]_ ,任何人都可以看到本书(包括源码),也可以用GitHub的方法参与到本书的开发中来。网络出版对于我和出版社杨编辑都是一个全新的体验。感谢Git,让我在一年内拥有了两种不同的出版体验。 ---- -.. [#] http://www.worldhello.net/gotgit/ +.. [#] http://gotgit.github.com/gotgit/ .. [#] https://github.com/gotgit/gotgithub diff --git a/_theme/gotgithub/layout.html b/_theme/gotgithub/layout.html index 92a1501..e12cb6c 100644 --- a/_theme/gotgithub/layout.html +++ b/_theme/gotgithub/layout.html @@ -43,14 +43,14 @@

World Hello

{%- if hasdoc('copyright') %} {% trans path=pathto('copyright'), copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} {%- else %} - {% trans copyright=copyright|e %}© Copyright {{ copyright }}。{% endtrans %} + {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} {%- endif %} {%- endif %} {%- if last_updated %} - {% trans last_updated=last_updated|e %}最后更新于 {{ last_updated }}。{% endtrans %} + {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} {%- endif %} {%- if show_sphinx %} - {% trans sphinx_version=sphinx_version|e %}使用 Sphinx {{ sphinx_version }} 创建。{% endtrans %} + {% trans sphinx_version=sphinx_version|e %}Created using Sphinx {{ sphinx_version }}.{% endtrans %} {%- endif %} diff --git a/_theme/gotgithub/static/sphinxdoc.css b/_theme/gotgithub/static/sphinxdoc.css index bae42cb..b80e129 100644 --- a/_theme/gotgithub/static/sphinxdoc.css +++ b/_theme/gotgithub/static/sphinxdoc.css @@ -148,8 +148,7 @@ a:hover { } div.body a { - text-decoration: none; - font-weight: normal; + text-decoration: underline; } h1 { @@ -247,17 +246,6 @@ pre { background-color: #f8f8f8; } -td pre { - font-family: 'Consolas', 'Deja Vu Sans Mono', - 'Bitstream Vera Sans Mono', monospace; - font-size: 1em; - letter-spacing: 0.015em; - line-height: 120%; - padding: 0em; - border: 0; - background-color: #ffffff; -} - pre a { color: inherit; text-decoration: underline; @@ -363,41 +351,3 @@ div.figure img { border: 1px solid #ccc; padding: 5px; } - -.footnote-reference { - font-size: smaller; - line-height: 0; - vertical-align: super; - margin: 0; - font-weight: normal; -} - -div.body a.footnote-reference { - text-decoration: none; -} - -table.classic { - border: 2px solid black; - border-collapse: collapse; - background: white; -} - -table.classic td, table.docutils th { - padding: 1px 8px 1px 5px; - border: 1px solid black; -} - -table.classic th { - background: #aaa; - color: white; - border: 1px solid black; - text-align: center; -} - -.strike { - text-decoration: line-through; -} - -.underline { - text-decoration: underline; -} diff --git a/_version.inc.in b/_version.inc.in deleted file mode 100644 index f1d6dea..0000000 --- a/_version.inc.in +++ /dev/null @@ -1,3 +0,0 @@ -:Author: Jiang Xin -:Version: -:Copyright: `Creative Commons BY-NC-SA `_ diff --git a/appendix/markups.rst b/appendix/markups.rst deleted file mode 100644 index 5775145..0000000 --- a/appendix/markups.rst +++ /dev/null @@ -1,1251 +0,0 @@ -.. _markups: - -====================== - 附录:轻量级标记语言 -====================== - -没有标记语言就没有Web和丰富多彩的互联网,但创造了Web的HTML语言并非尽善尽美,\ -存在诸如难读、难写、难以向其他格式转换的问题。究其根源是因为HTML语言是一种\ -“重”标记语言,对机器友好而并非对人友好。 - -下面这段HTML源码,非技术控阅读起来会遇到困难。 - -:: - - - - - 轻量级标记语言 - - -

轻量级标记语言

- -

轻量级标记语言 是一种 语法简单 的标记语言。 - 它使用易于理解的格式标记,没有古怪的 <标签> 。

- -
    -
  • 可以使用最简单的文本编辑器编辑。
  • -
  • 所见即所得,非技术控亦可直接阅读源码。
  • -
  • 可版本控制。
  • -
  • 实现单一源文件出版。
  • -
- - - -同样的信息如果换用轻量级标记语言来表达,就非常直观了。如下所示: - -:: - - 轻量级标记语言 - ============== - - **轻量级标记语言** 是一种 *语法简单* 的标记语言。 - 它使用易于理解的格式标记,没有古怪的 `<标签>` 。 - - - 可以使用最简单的文本编辑器编辑。 - - 所见即所得,非技术控亦可直接阅读源码。 - - 可版本控制。 - - 实现单一源文件出版。 - -GitHub令人着迷的一个因素就在于GitHub为用户提供更为便捷地创建UGC\ -(用户生成内容)的方法,其奥秘就在于使用了轻量级标记语言。\ -无论是代码提交说明、提交评注、问题描述、项目的README文件、维基页面、\ -用户主页和项目主页都可以使用Markdown\ [#]_\ 等轻量级标记语言来撰写。\ -轻量级标记语言如Markdown是对人友好的标记语言,一些语法参照了\ -我们写电子邮件时的习惯,即使第一次接触用轻量级标记语言撰写的文件,也可以\ -毫无障碍地理解其中的内容。 - -虽然GitHub更倾向于使用Markdown标记语言\ [#]_\ ,但很多地方也提供对其他轻量级\ -标记语言的支持。包括为Python程序员所熟悉的reStructedText\ [#]_\ ,为Ruby程序员\ -所熟悉的Textile\ [#]_\ 、RDoc\ [#]_\ ,为Perl程序员所熟悉的POD\ [#]_\ ,\ -为Emacs用户所熟悉的Org-mode\ [#]_\ ,为维基用户所熟悉的MediaWiki\ [#]_\ 和\ -Creole\ [#]_\ ,以及可作为DocBook\ [#]_\ 前端的颇有前途的AsciiDoc\ [#]_\ 标记语言。 - -下面通过一张表格对几种常用的轻量级标记语言加以对照,供有不同标记语言偏好的\ -用户参考,便于在GitHub某些不能随意更换标记语言而只能使用GFM(GitHub风格的\ -Markdown)的场合可以自如地转换。 - -在“\ :ref:`tbl-markups`\ ”中,为使表格更加紧凑使用代号表示各种标记语言。\ -例如:md为Markdown,gfm是GitHub风格的Markdown,rst为reStructedText,\ -ttl为Textile,asc为AsciiDoc,org为Org-mode。 - - -.. highlight:: none -.. role:: raw-html(raw) - :format: html -.. role:: strike - :class: strike -.. role:: ul - :class: underline - -.. _tbl-markups: - -.. table:: 表7-1:常用轻量级标记语言对照 - :class: classic - - +----------------------+-----------------------------+-------------------------------------------------+-----------------------------------------------+ - | | 标记语言 | | | - | +-----+-----+-----+-----+-----+ | | - | 类别 | MD | RST | TTL | ASC | ORG | 代码示例 | 输出示例 | - +======================+=====+=====+=====+=====+=====+=================================================+===============================================+ - | 标题 | md | | | | | :: | | - | | | | | | | | 输出略。 | - | | | | | | | # 一级标题 | | - | | | | | | | ## 二级标题 | .. note:: | - | | | | | | | ### 三级标题 | - 标题后面可接匹配的井号。 | - | | | | | | | #### 四级标题 | | - | | | | | | | ##### 五级标题 | - Markdown的前两级标题还可以使用\ | - | | | | | | | ###### 六级标题 ###### | reST风格,即在标题下衬以等号\ | - | | | | | | | | 或减号组成的下划线。 | - | | | | | | | | | - | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | rst | | | | :: | | - | | | | | | | | 输出略。 | - | | | | | | | 一级标题 | | - | | | | | | | ======== | .. note:: | - | | | | | | | | - 标题级别和下划线无对应,文档中保持\ | - | | | | | | | 二级标题 | 一致就好。 | - | | | | | | | -------- | - reST标题可用下列符号标记: | - | | | | | | | | # \* = - ^ ~ \` : . \ | - | | | | | | | 三级标题 | _ + \" 等。 | - | | | | | | | ~~~~~~~~ | | - | | | | | | | | | - | | | | | | | 四级标题 | | - | | | | | | | ^^^^^^^^ | | - | | | | | | | | | - | | | | | | | 五级标题 | | - | | | | | | | ++++++++ | | - | | | | | | | | | - | | | | | | | 六级标题 | | - | | | | | | | ```````` | | - | | | | | | | | | - | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | ttl | | | :: | | - | | | | | | | | 输出略。 | - | | | | | | | h1. 一级标题 | | - | | | | | | | h2. 二级标题 | | - | | | | | | | h3. 三级标题 | | - | | | | | | | h4. 四级标题 | | - | | | | | | | h5. 五级标题 | | - | | | | | | | h6. 六级标题 | | - | | | | | | | | | - | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | | asc | | AsciiDoc 提供两种风格的标题。 | 输出略。 | - | | | | | | | | | - | | | | | | | - 下划线风格标题。 | | - | | | | | | | | | - | | | | | | | :: | | - | | | | | | | | | - | | | | | | | 文档标题 | .. note:: 除了两种不同风格的标题外,\ | - | | | | | | | ======== | 还支持以点开始的块标题,\ | - | | | | | | | | 块标题不生成目录。如: | - | | | | | | | 一级标题 | | - | | | | | | | -------- | :: | - | | | | | | | | | - | | | | | | | 二级标题 | .BlockTitle | - | | | | | | | ~~~~~~~~ | | - | | | | | | | | | - | | | | | | | 三级标题 | | - | | | | | | | ^^^^^^^^ | | - | | | | | | | | | - | | | | | | | 四级标题 | | - | | | | | | | ++++++++ | | - | | | | | | | | | - | | | | | | | - 单行风格标题。 | | - | | | | | | | | | - | | | | | | | :: | | - | | | | | | | | | - | | | | | | | = 文档标题 = | | - | | | | | | | == 一级标题 == | | - | | | | | | | === 二级标题 === | | - | | | | | | | ==== 三级标题 ==== | | - | | | | | | | ===== 四级标题 ===== | | - | | | | | | | | | - | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | | | org | :: | | - | | | | | | | | 输出略。 | - | | | | | | | * 一级标题 | | - | | | | | | | ** 二级标题 | .. note:: 为支持更多标题级别需要设置 | - | | | | | | | *** 三级标题 | ``#+OPTIONS: H:6``\ 。 | - | | | | | | | | | - +----------+-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | 段落 | 空行分段 | md | rst | ttl | asc | org | :: | | - | | | | | | | | | | - | | | | | | | | 第一段内容。 | 第一段内容。 | - | | | | | | | | | | - | | | | | | | | 第二段和第一段间有一空行。 | 第二段和第一段间有一空行。 | - | | | | | | | | | | - | +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | 自动续行 | md | rst | | asc | org | :: | | - | | | | | | | | | | - | | | | | | | | 一个回车不分段, | 一个回车不分段,°\ | - | | | | | | | | 本行续上行。 | 本行续上行。 | - | | | | | | | | | | - | | | | | | | | | | - | +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | 不留白\ | | rst | | | | :: | | - | | 续行 | | | | | | | | - | | | | | | | | 行尾转义字符让\ | 行尾转义字符让\ | - | | | | | | | | 续行之间不留白。 | 续行之间不留白。 | - | | | | | | | | | | - | +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | 插入换行 | md | | | | | :: | | - | | | | | | | | | | - | | | | | | | | 行尾两空格°° | | 行尾两空格 | - | | | | | | | | 保持换行。 | | 保持换行。 | - | | | | | | | | | | - | | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | gfm | | ttl | | | :: | | - | | | | | | | | | | - | | | | | | | | GFM、Textile等 | | GFM、Textile等 | - | | | | | | | | 保持段落内换行符。 | | 保持段落内换行符。 | - | | | | | | | | | | - | | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | rst | | | | :: | | - | | | | | | | | | | - | | | | | | | | | 保持换行符, | | 保持换行符, | - | | | | | | | | | 本行不续行。 | | 本行不续行。 | - | | | | | | | | | | - | | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | rst | | | | :: | | - | | | | | | | | | | - | | | | | | | | .. role:: raw-html(raw) | .. role:: raw-html(raw) | - | | | | | | | | :format: html | :format: html | - | | | | | | | | | | - | | | | | | | | 用新定义的role插入换行, | 用新定义的role插入换行, | - | | | | | | | | :raw-html:`
` | :raw-html:`
` | - | | | | | | | | 本行不再续行。 | 本行不再续行。 | - | | | | | | | | | | - | | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | | | asc | | :: | | - | | | | | | | | | | - | | | | | | | | 行尾的空格和加号 + | | 行尾的空格和加号 | - | | | | | | | | 保持换行。 | | 保持换行。 | - | | | | | | | | | | - | | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | | | | org*| :: | | - | | | | | | | | | | - | | | | | | | | 行尾两个反斜线\\ | | 行尾两个反斜线 | - | | | | | | | | 保持段落内换行符。 | | 保持段落内换行符。 | - | | | | | | | | | | - | +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | 段落缩进 | md | rst | | | | :: | | - | | | | | | | | | | - | | | | | | | | 邮件体段落缩进: | 邮件体段落缩进: | - | | | | | | | | | | - | | | | | | | | > 第一级段落缩进。 | 第一级段落缩进。 | - | | | | | | | | > | | - | | | | | | | | > > 第二级段落缩进。 | 第二级段落缩进。 | - | | | | | | | | > | | - | | | | | | | | > 返回一级段落缩进。 | 返回一级段落缩进。 | - | | | | | | | | | | - | | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | rst | | | | :: | | - | | | | | | | | | | - | | | | | | | | Python式段落缩进: | Python式段落缩进: | - | | | | | | | | | | - | | | | | | | | 第一级段落缩进。 | 第一级段落缩进。 | - | | | | | | | | | | - | | | | | | | | 第二级段落缩进。 | 第二级段落缩进。 | - | | | | | | | | | | - | | | | | | | | 返回一级段落缩进。 | 返回一级段落缩进。 | - | | | | | | | | | | - | | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | | ttl | | | :: | | - | | | | | | | | | | - | | | | | | | | Textile式段落缩进: | Textile式段落缩进: | - | | | | | | | | | | - | | | | | | | | bq. 本段缩进。 | 本段缩进。 | - | | | | | | | | | | - | | | | | | | | 正常段落。 | 正常段落。 | - | | | | | | | | | | - | | | | | | | | bq.. 注意缩进关键字后有两个点。 | 注意缩进关键字后有两个点。 | - | | | | | | | | | | - | | | | | | | | 后续段落持续缩进, | | 后续段落持续缩进, | - | | | | | | | | 直至遇到 p. 定义的段落。 | | 直至遇到 p. 定义的段落。 | - | | | | | | | | | | - | | | | | | | | p. 正常段落不再缩进。 | 正常段落不再缩进。 | - | | | | | | | | | | - | | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | | | asc | | :: | | - | | | | | | | | | | - | | | | | | | | 四个或以上的下划线括起的区域为引言缩进。 | 四个或以上的下划线括起的区域为引言缩进。 | - | | | | | | | | | | - | | | | | | | | [quote, author, source] | 引言... | - | | | | | | | | ______________________________ | | - | | | | | | | | 引言... | source | - | | | | | | | | ______________________________ | | - | | | | | | | | | —— author | - | | | | | | | | | | - | | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | | | | org | :: | | - | | | | | | | | | | - | | | | | | | | Org-mode式段落缩进: | Org-mode式段落缩进: | - | | | | | | | | | | - | | | | | | | | #+BEGIN_QUOTE | 段落缩进。 | - | | | | | | | | 段落缩进。 | | - | | | | | | | | #+END_QUOTE | | - | | | | | | | | | | - +----------+-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | 代码块 | md | | | | | :: | 四个空格缩进是代码块: | - | | | | | | | | | - | | | | | | | 四个空格缩进是代码块: | :: | - | | | | | | | | | - | | | | | | | $ printf "Hello, world.\n" | $ printf "Hello, world.\n" | - | | | | | | | | | - | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | gfm | | | | | :: | 三个连续的`或~等符号界定代码块。 | - | | | | | | | | | - | | | | | | | 三个连续的`或~等符号界定代码块。 | .. code-block:: ruby | - | | | | | | | | | - | | | | | | | ```ruby | require 'redcarpet' | - | | | | | | | require 'redcarpet' | md = Redcarpet.new("Hello, world.") | - | | | | | | | md = Redcarpet.new("Hello, world.") | puts md.to_html | - | | | | | | | puts md.to_html | | - | | | | | | | ``` | | - | | | | | | | | | - | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | rst | | | | :: | | - | | | | | | | | | - | | | | | | | 双冒号后缩进为代码块。 | 双冒号后缩进为代码块。 | - | | | | | | | | | - | | | | | | | :: | :: | - | | | | | | | | | - | | | | | | | $ printf "Hello, world.\n" | $ printf "Hello, world.\n" | - | | | | | | | | | - | | | | | | | 还可声明语言类型实现语法加亮。 | 还可声明语言类型实现语法加亮。 | - | | | | | | | | | - | | | | | | | .. code-block:: sh | .. code-block:: sh | - | | | | | | | | | - | | | | | | | $ printf "Hello, world.\n" | $ printf "Hello, world.\n" | - | | | | | | | | | - | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | ttl | | | :: | 以bc.或bc..指令开头的是代码块。 | - | | | | | | | | | - | | | | | | | 以bc.或bc..指令开头的是代码块。 | :: | - | | | | | | | | | - | | | | | | | bc.. $ git init | $ git init | - | | | | | | | | | - | | | | | | | $ git commit --allow-empty | $ git commit --allow-empty | - | | | | | | | | | - | | | | | | | p. 本段不再是代码块。 | 本段不再是代码块。 | - | | | | | | | | | - | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | ttl | | | :: | 原样格式输出,相当于
标签。               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   原样格式输出,相当于
标签。               | ::                                            |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   pre..                                         |              更上一层楼                       |
-   |                      |     |     |     |     |     |              更上一层楼                         |   欲穷千里目                                  |
-   |                      |     |     |     |     |     |   欲穷千里目                                    |                                               |
-   |                      |     |     |     |     |     |                                                 | 恢复正常段落。                                |
-   |                      |     |     |     |     |     |   p. 恢复正常段落。                             |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     |     |     | asc |     | ::                                              |                                               |
-   |                      |     |     |     |     |     |                                                 | 四个或更多减号括起代码块,                    |
-   |                      |     |     |     |     |     |   四个或更多减号括起代码块,                    | 还可声明语言种类。                            |
-   |                      |     |     |     |     |     |   还可声明语言种类。                            |                                               |
-   |                      |     |     |     |     |     |                                                 | .. code-block:: c                             |
-   |                      |     |     |     |     |     |   [source, c]                                   |                                               |
-   |                      |     |     |     |     |     |   -----------------------------                 |    #include                          |
-   |                      |     |     |     |     |     |   #include                             |                                               |
-   |                      |     |     |     |     |     |                                                 |    int main() {                               |
-   |                      |     |     |     |     |     |   int main() {                                  |       printf("Hello World!\n");               |
-   |                      |     |     |     |     |     |      printf("Hello World!\n");                  |       exit(0);                                |
-   |                      |     |     |     |     |     |      exit(0);                                   |    }                                          |
-   |                      |     |     |     |     |     |   }                                             |                                               |
-   |                      |     |     |     |     |     |   -----------------------------                 |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     |     |     | asc |     | ::                                              | 正常段落。                                    |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   正常段落。                                    | ::                                            |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |     缩进段落相当于添加
标签,               |   缩进段落相当于添加
标签,               |
-   |                      |     |     |     |     |     |     等宽字体,原样输出。                        |   等宽字体,原样输出。                        |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   缩进会和其他语法如列表相混淆,                | 缩进会和其他语法如列表相混淆,                |
-   |                      |     |     |     |     |     |   可用 `[literal]` 显示声明。                   | 可用 ``[literal]`` 显示声明。                 |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   [literal]                                     | ::                                            |
-   |                      |     |     |     |     |     |   原样输出,                                    |                                               |
-   |                      |     |     |     |     |     |   显示为等宽字体。                              |   原样输出,                                  |
-   |                      |     |     |     |     |     |                                                 |   显示为等宽字体。                            |
-   |                      |     |     |     |     |     |   或用四个以上点组成的定界符标记。              |                                               |
-   |                      |     |     |     |     |     |                                                 | 或用四个以上点组成的定界符标记。              |
-   |                      |     |     |     |     |     |   ..............................                |                                               |
-   |                      |     |     |     |     |     |   原样输出,                                    | ::                                            |
-   |                      |     |     |     |     |     |   显示为等宽字体。                              |                                               |
-   |                      |     |     |     |     |     |   ..............................                |   原样输出,                                  |
-   |                      |     |     |     |     |     |                                                 |   显示为等宽字体。                            |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     |     |     |     | org | ::                                              | 下面是代码块。                                |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   下面是代码块。                                | .. code-block:: ruby                          |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   #+BEGIN_SRC ruby                              |   require 'redcarpet'                         |
-   |                      |     |     |     |     |     |     require 'redcarpet'                         |   md = Redcarpet.new("Hello, world.")         |
-   |                      |     |     |     |     |     |     md = Redcarpet.new("Hello, world.")         |   puts md.to_html                             |
-   |                      |     |     |     |     |     |     puts md.to_html                             |                                               |
-   |                      |     |     |     |     |     |   #+END_SRC                                     |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   +----------+-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   | 列表     | 无序列表  | md  | rst |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   * 星号、减号、加号开始列表。                  | * 星号、减号、加号开始列表。                  |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |     - 列表层级和缩进有关。                      |   - 列表层级和缩进有关。                      |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |       + 和具体符号无关。                        |     + 和具体符号无关。                        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   * 返回一级列表。                              | * 返回一级列表。                              |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     | ttl |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   * 星号开始无序列表。                          | * 星号开始无序列表。                          |
-   |          |           |     |     |     |     |     |   ** 更多星号代表不同层级。                     |                                               |
-   |          |           |     |     |     |     |     |   *** 三级列表。                                |   * 更多星号代表不同层级。                    |
-   |          |           |     |     |     |     |     |   * 返回一级列表。                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |     * 三级列表。                              |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 | * 返回一级列表。                              |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     | asc |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 | * 1个减号开始列表。                           |
-   |          |           |     |     |     |     |     |   - 1个减号开始列表。                           |                                               |
-   |          |           |     |     |     |     |     |   * 或1到5个星号开始列表。                      |   - 或1到5个星号开始列表。                    |
-   |          |           |     |     |     |     |     |   ** 三级列表。                                 |                                               |
-   |          |           |     |     |     |     |     |   - 返回一级列表。                              |     + 三级列表。                              |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 | * 返回一级列表。                              |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     |     | org | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   列表语法和Markdown、reST类似。                | 列表语法和Markdown、reST类似。                |
-   |          |           |     |     |     |     |     |   星号和列表语法冲突需缩进,不建议使用。        | 星号和列表语法冲突需缩进,不建议使用。        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |     - 减号、加号开始列表。                      | - 减号、加号开始列表。                        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |       + 列表层级和缩进有关。                    |   + 列表层级和缩进有关。                      |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |         - 和具体符号无关。                      |     - 和具体符号无关。                        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |     - 返回一级列表。                            | - 返回一级列表。                              |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          | 有序列表  | md  |     |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   1. 数字和点开始有序列表。                     | 1. 数字和点开始有序列表。                     |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |      1. 注意子列表的缩进位置。                  |    1. 注意子列表的缩进位置。                  |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |         1. 三级列表。                           |       1. 三级列表。                           |
-   |          |           |     |     |     |     |     |         1. 编号会自动更正。                     |       2. 编号会自动更正。                     |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |      1. 二级列表,编号自动更正为2。             |    2. 二级列表,编号自动更正为2。             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   2. 返回一级列表。                             | 2. 返回一级列表。                             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     | rst |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   1. 数字和点是一种编号方式。                   | 1. 数字和点是一种编号方式。                   |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |      A. 大写字母编号。                          |    A. 大写字母编号。                          |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |         a. 小写字母编号。                       |       a. 小写字母编号。                       |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   2. 继续一级列表。                             | 2. 继续一级列表。                             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |      (I) 大写罗马编号。                         |    (I) 大写罗马编号。                         |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |          i) 小写罗马编号。                      |        i) 小写罗马编号。                      |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     | ttl |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   # 井号开始有序列表。                          | 1. 井号开始有序列表。                         |
-   |          |           |     |     |     |     |     |   # 有序列表自动编号。                          | 2. 有序列表自动编号。                         |
-   |          |           |     |     |     |     |     |   ## 更多井号代表不同层级。                     |                                               |
-   |          |           |     |     |     |     |     |   ### 三级列表。                                |    1. 更多井号代表不同层级。                  |
-   |          |           |     |     |     |     |     |   # 返回一级列表。                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |       1. 三级列表。                           |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 | 3. 返回一级列表。                             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     | asc |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   1. 和reST一样支持多种编号方式。               | 1. 和reST一样支持多种编号方式。               |
-   |          |           |     |     |     |     |     |   a. 层级靠列表风格决定,而非缩进。             |                                               |
-   |          |           |     |     |     |     |     |   A. 三级列表。                                 |    a. 层级靠列表风格决定,而非缩进。          |
-   |          |           |     |     |     |     |     |   b. 返回二级列表。                             |                                               |
-   |          |           |     |     |     |     |     |   i) 罗马数字列表。                             |       A. 三级列表。                           |
-   |          |           |     |     |     |     |     |   IX)  大写罗马。编号自动纠正。                 |                                               |
-   |          |           |     |     |     |     |     |   2. 返回一级列表。                             |    b. 返回二级列表。                          |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 |       i) 罗马数字列表。                       |
-   |          |           |     |     |     |     |     | .. note:: 还可以用1到5个点开始有序列表,        |                                               |
-   |          |           |     |     |     |     |     |           自动按数字、字母方式编号。如:        |          IX)  大写罗马。编号自动纠正。        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |           ::                                    | 2. 返回一级列表。                             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |             . 数字一级列表。                    |                                               |
-   |          |           |     |     |     |     |     |             .. 字母二级列表。                   |                                               |
-   |          |           |     |     |     |     |     |             ... 罗马数字三级列表。              |                                               |
-   |          |           |     |     |     |     |     |             .... 大写字母四级列表。             |                                               |
-   |          |           |     |     |     |     |     |             ..... 大写罗马五级列表。            |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     |     | org | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   1. 数字和点或右括号开始有序列表。             | 1. 数字和点或右括号开始有序列表。             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |      1) 缩进即为子列表。                        |    1. 缩进即为子列表。                        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |         1. 三级列表。                           |       1. 三级列表。                           |
-   |          |           |     |     |     |     |     |         1. 编号会自动更正。                     |       2. 编号会自动更正。                     |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |      2) 二级列表。                              |    2. 二级列表。                              |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   2. 返回一级列表。                             | 2. 返回一级列表。                             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          | 列表续行\ | md  |     |     |     |     | ::                                              |                                               |
-   |          | 、段落\   |     |     |     |     |     |                                                 |                                               |
-   |          | 和代码块  |     |     |     |     |     |   1. 列表项可以折行,                           | 1. 列表项可以折行,                           |
-   |          |           |     |     |     |     |     |      对齐则自动续行。                           |    对齐则自动续行。                           |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   2. 列表项可包含多个段落。                     | 2. 列表项可包含多个段落。                     |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |       空行开始的新段落必须缩进四个空格,        |    空行开始的新段落必须缩进四个空格,         |
-   |          |           |     |     |     |     |     |       段落才属于列表项。                        |    段落才属于列表项。                         |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   3. 列表中的代码块要缩进8个空格。              | 3. 列表中的代码块要缩进8个空格。              |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |           $ printf "Hello, world.\n"            |    ::                                         |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 |      $ printf "Hello, world.\n"               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     | rst |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   1. 列表项可以折行,                           | 1. 列表项可以折行,                           |
-   |          |           |     |     |     |     |     |      对齐则自动续行。                           |    对齐则自动续行。                           |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   2. 列表项可包含多个段落。                     | 2. 列表项可包含多个段落。                     |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |      空行开始的新段落,                         |    空行开始的新段落,                         |
-   |          |           |     |     |     |     |     |      新段落要和列表项内容对齐。                 |    新段落要和列表项内容对齐。                 |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   3. 列表下的代码段注意对齐即可。               | 3. 列表下的代码段注意对齐即可。               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |      ::                                         |    ::                                         |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |        $ printf "Hello, world.\n"               |      $ printf "Hello, world.\n"               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     | asc |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   1. 列表项可以折行,                           | 1. 列表项可以折行,                           |
-   |          |           |     |     |     |     |     |      对齐则自动续行。                           |    对齐则自动续行。                           |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   2. 列表项可包含多个段落。                     | 2. 列表项可包含多个段落。                     |
-   |          |           |     |     |     |     |     |   +                                             |                                               |
-   |          |           |     |     |     |     |     |   加号代表本段落属于列表。                      |    加号代表本段落属于列表。                   |
-   |          |           |     |     |     |     |     |   +                                             |                                               |
-   |          |           |     |     |     |     |     |   --                                            |    两个减号包裹的块作为一整体                 |
-   |          |           |     |     |     |     |     |   两个减号包裹的块作为一整体                    |    属于列表。                                 |
-   |          |           |     |     |     |     |     |   属于列表。                                    |                                               |
-   |          |           |     |     |     |     |     |                                                 |    其中分段无需再使用加号。                   |
-   |          |           |     |     |     |     |     |   其中分段无需再使用加号。                      |                                               |
-   |          |           |     |     |     |     |     |   --                                            | 3. 注意列表项内代码段前空行用加号替换。       |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   3. 注意列表项内代码段前空行用加号替换。       |    ::                                         |
-   |          |           |     |     |     |     |     |   +                                             |                                               |
-   |          |           |     |     |     |     |     |   --------                                      |      $ printf "Hello, world.\n"               |
-   |          |           |     |     |     |     |     |   $ printf "Hello, world.\n"                    |                                               |
-   |          |           |     |     |     |     |     |   --------                                      |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     |     | org | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   1. 列表项可以折行,                           | 1. 列表项可以折行,                           |
-   |          |           |     |     |     |     |     |      对齐则自动续行。                           |    对齐则自动续行。                           |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   2. 列表项可包含多个段落。                     | 2. 列表项可包含多个段落。                     |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |      空行开始的新段落,                         |    空行开始的新段落,                         |
-   |          |           |     |     |     |     |     |      新段落和列表项内容对齐即可。               |    新段落和列表项内容对齐即可。               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   3. 列表下的代码段注意缩进。                   | 3. 列表下的代码段注意缩进。                   |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |      #+BEGIN_SRC bash                           |    ::                                         |
-   |          |           |     |     |     |     |     |        $ printf "Hello, world.\n"               |                                               |
-   |          |           |     |     |     |     |     |      #+END_SRC                                  |      $ printf "Hello, world.\n"               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          | 定义      |     | rst |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   git                                           | git                                           |
-   |          |           |     |     |     |     |     |     Simple and beautiful.                       |   Simple and beautiful.                       |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   hg                                            | hg                                            |
-   |          |           |     |     |     |     |     |     Another DVCS.                               |   Another DVCS.                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   subversion                                    | subversion                                    |
-   |          |           |     |     |     |     |     |     VCS with many constrains.                   |   VCS with many constrains.                   |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |     Why not Git?                                |   Why not Git?                                |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     | ttl |     |     | ::                                              | git                                           |
-   |          |           |     |     |     |     |     |                                                 |   Simple and beautiful.                       |
-   |          |           |     |     |     |     |     |   - git := Simple and beautiful.                |                                               |
-   |          |           |     |     |     |     |     |   - hg := Another DVCS.                         | hg                                            |
-   |          |           |     |     |     |     |     |   - subversion :=                               |   Another DVCS.                               |
-   |          |           |     |     |     |     |     |   VCS with many constrains.                     |                                               |
-   |          |           |     |     |     |     |     |                                                 | subversion                                    |
-   |          |           |     |     |     |     |     |   Why not Git? =:                               |   VCS with many constrains.                   |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 |   Why not Git?                                |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     | asc |     | ::                                              | git                                           |
-   |          |           |     |     |     |     |     |                                                 |   Simple and beautiful.                       |
-   |          |           |     |     |     |     |     |   git ::                                        |                                               |
-   |          |           |     |     |     |     |     |       Simple and beautiful.                     | hg                                            |
-   |          |           |     |     |     |     |     |   hg :: Another DVCS.                           |   Another DVCS.                               |
-   |          |           |     |     |     |     |     |   subversion :: VCS with many constrains.       |                                               |
-   |          |           |     |     |     |     |     |                 +                               | subversion                                    |
-   |          |           |     |     |     |     |     |                 Why not Git?                    |   VCS with many constrains.                   |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 |   Why not Git?                                |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     |     | org | ::                                              | git                                           |
-   |          |           |     |     |     |     |     |                                                 |   Simple and beautiful.                       |
-   |          |           |     |     |     |     |     |   - git :: Simple and beautiful.                |                                               |
-   |          |           |     |     |     |     |     |   - hg :: Another DVCS.                         | hg                                            |
-   |          |           |     |     |     |     |     |   - subversion :: VCS with many constrains.     |   Another DVCS.                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                   Why not Git?                  | subversion                                    |
-   |          |           |     |     |     |     |     |                                                 |   VCS with many constrains.                   |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 |   Why not Git?                                |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   +----------+-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   | 分隔线               | md  |     | ttl |     |     | ::                                              | 输出略。                                      |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   三条或更多短线(或星号、下划线)\             |                                               |
-   |                      |     |     |     |     |     |   显示为分隔线。                                |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   ---                                           |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     | rst |     |     |     | ::                                              | 输出略。                                      |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   四条短线或以上显示为分隔线。                  |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   ----                                          |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     |     |     | asc |     | ::                                              | 输出略。                                      |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   三个或更多的单引号作为分割线。                |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   '''                                           |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     |     |     |     | org | ::                                              | 输出略。                                      |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   五条短线或以上显示为分隔线。                  |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   -----                                         |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   +----------+-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   | 字体     | 粗体和\   | md  |     |     |     |     | ::                                              |                                               |
-   |          | 斜体      |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   这些都是 **粗体** 或 __粗体__ ,              | 这些都是 **粗体** 或 **粗体** ,              |
-   |          |           |     |     |     |     |     |   这写都是 *斜体* 或 _斜体_ 。                  | 这些都是 *斜体* 或 *斜体* 。                  |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     | rst |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   这是 **粗体** ,这是 *斜体* 。                | 这是 **粗体** ,这是 *斜体* 。                |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   不留白的\ **粗体**\ 和\ *斜体*\ 效果。        | 不留白的\ **粗体**\ 和\ *斜体*\ 效果。        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     | ttl |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   这些都是 *粗体* 或 **粗体** ,                | 这些都是 **粗体** 或 **粗体** ,              |
-   |          |           |     |     |     |     |     |   这些都是 _斜体_ 或 __斜体__ 。                | 这些都是 *斜体* 或 *斜体* 。                  |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   不留白的[*粗体*]和[_斜体_]效果。              | 不留白的\ **粗体**\ 和\ *斜体*\ 效果。        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     | asc |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   这是 *粗体* ,                                | 这是 **粗体** ,                              |
-   |          |           |     |     |     |     |     |   这是 _斜体_ 或 '斜体' 。                      | 这是 *斜体* 或 *斜体* 。                      |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   不留白的**粗体**和__斜体__效果。              | 不留白的\ **粗体**\ 和\ *斜体*\ 效果。        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     |     | org | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   这是 *粗体* ,这是 /斜体/ 。                  | 这是 **粗体** ,这是 *斜体* 。                |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          | 删除线    | gfm |     |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   ~~删除线~~ 效果                               | :strike:`删除线` 效果                         |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     | rst |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   .. role:: strike                              |                                               |
-   |          |           |     |     |     |     |     |      :class: strike                             |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   :strike:`删除线` 效果                         | :strike:`删除线` 效果                         |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   不留白的\ :strike:`删除线`\ 效果              | 不留白的\ :strike:`删除线`\ 效果              |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     | ttl |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   -删除线- 效果                                 | :strike:`删除线` 效果                         |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   不留白的[-删除线-]效果                        | 不留白的\ :strike:`删除线`\ 效果              |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     | asc |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   [line-through]#删除线# 效果                   | :strike:`删除线` 效果                         |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   不留白的[line-through]##删除线##效果          | 不留白的\ :strike:`删除线`\ 效果              |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     |     | org | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   +删除线+ 效果                                 | :strike:`删除线` 效果                         |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          | 下划线    | md  |     |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   下划线 效果                            | :ul:`下划线` 效果                             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     | rst |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   .. role:: ul                                  |                                               |
-   |          |           |     |     |     |     |     |      :class: underline                          |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   :ul:`下划线` 效果                             | :ul:`下划线` 效果                             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   不留白的\ :ul:`下划线`\ 效果                  | 不留白的\ :ul:`下划线`\ 效果                  |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     | ttl |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   +下划线+ 效果                                 | :ul:`下划线` 效果                             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   不留白的[+下划线+]效果                        | 不留白的\ :ul:`下划线`\ 效果                  |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     | asc |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   [underline]#下划线# 效果                      | :ul:`下划线` 效果                             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   不留白的[underline]##下划线##效果             | 不留白的\ :ul:`下划线`\ 效果                  |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     |     | org | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   _下划线_ 效果                                 | :ul:`下划线` 效果                             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          | 上标、\   | md  |     |     |     |     | ::                                              |                                               |
-   |          | 下标      |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - Water: H2O                       | - Water: H\ :sub:`2`\ O                       |
-   |          |           |     |     |     |     |     |   - E = mc2                          | - E = mc\ :sup:`2`                            |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 | .. note:: 通过直接嵌入HTML代码实现。          |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     | rst |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - Water: H\ :sub:`2`\ O                       | - Water: H\ :sub:`2`\ O                       |
-   |          |           |     |     |     |     |     |   - E = mc\ :sup:`2`                            | - E = mc\ :sup:`2`                            |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     | ttl |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - Water: H[~2~]O                              | - Water: H\ :sub:`2`\ O                       |
-   |          |           |     |     |     |     |     |   - E = mc[^2^]                                 | - E = mc\ :sup:`2`                            |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     | asc |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 | - Water: H\ :sub:`2`\ O                       |
-   |          |           |     |     |     |     |     |   - Water: H~2~O                                | - E = mc\ :sup:`2`                            |
-   |          |           |     |     |     |     |     |   - E = mc^2^                                   |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     |     | org | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - Water: H_2 O                                | - Water: H\ :sub:`2` O                        |
-   |          |           |     |     |     |     |     |   - E = mc^2                                    | - E = mc\ :sup:`2`                            |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          | 等宽字体  | md  |     |     | asc |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   行内反引号嵌入代码,如: `git status` 。       | 行内反引号嵌入代码,如: ``git status`` 。     |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     | rst |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   两个连续反引号嵌入代码,如: ``git status`` 。 | 两个连续反引号嵌入代码,如: ``git status`` 。 |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 | .. note:: 相当于 \:literal:\`git status\` 。  |
-   |          |           |     |     |     |     |     |                                                 |           只用一个反引号则相当于 \            |
-   |          |           |     |     |     |     |     |                                                 |           \:title-reference:\`引言\` 。       |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     | ttl |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   行内用字符@嵌入代码,如: @git status@ 。      | 行内用字符@嵌入代码,如: ``git status`` 。    |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     | asc |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   行内用加号或反引号标识等宽字体,如:           | 行内用加号或反引号标识等宽字体,如:           |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 命令: +git clone+ 。                        | - 命令: ``git clone`` 。                      |
-   |          |           |     |     |     |     |     |   - 命令: `git init` 。                         | - 命令: ``git init`` 。                       |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     |     | org | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   行内用字符=或~嵌入代码,如:                   | 行内用字符=或~嵌入代码,如:                   |
-   |          |           |     |     |     |     |     |   =git status= 和 ~git st~ 。                   | ``git status`` 和 ``git st`` 。               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          | 引言      |     | rst |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   `Got GitHub` by Jiang Xin.                    | `Got GitHub` by Jiang Xin.                    |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     | ttl |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   ??Got GitHub?? by Jiang Xin.                  | `Got GitHub` by Jiang Xin.                    |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          | 清除\     |     | rst |     |     |     | ::                                              |                                               |
-   |          | 标记空白  |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   标记符号前后空白\                             | 标记符号前后空白\                             |
-   |          |           |     |     |     |     |     |   用\ **反斜线**\ 消除                          | 用\ **反斜线**\ 消除                          |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   +----------+-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   | 链接     | URL\      | gfm | rst |     | asc | org | ::                                              |                                               |
-   |          | 自动链接  |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 网址 http://github.com/                     | - 网址 http://github.com/                     |
-   |          |           |     |     |     |     |     |   - 邮件 me@foo.bar                             | - 邮件 me@foo.bar                             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          | 文字链接  | md  |     |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 | - 访问 `Google `__         |
-   |          |           |     |     |     |     |     |   - 访问 [Google](http://google.com "Search")   | - 访问 `GitHub`_                              |
-   |          |           |     |     |     |     |     |   - 访问 [GitHub][1]                            | - 访问 `WorldHello`_                          |
-   |          |           |     |     |     |     |     |   - 访问 [WorldHello][]                         |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |    [1]: http://github.com "Git host"            | .. _GitHub: http://github.com                 |
-   |          |           |     |     |     |     |     |    [worldhello]: http://www.worldhello.net      | .. _WorldHello: http://www.worldhello.net     |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     | rst |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 访问 `Google `_ 。      | - 访问 `Google `_\ 。     |
-   |          |           |     |     |     |     |     |   - 上面已定义,直接引用 google_ 链接。         | - 上面已定义,直接引用 google_ 链接。         |
-   |          |           |     |     |     |     |     |   - 链接地址在后面定义,如: GitHub_ 。         | - 链接地址在后面定义,如: GitHub_\ 。        |
-   |          |           |     |     |     |     |     |   - 反引号括起多个单词的链接。如 `my blog`_ 。  | - 反引号括起多个单词的链接。如 `my blog`_\ 。 |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   .. _GitHub: http://github.com                 | .. _GitHub: http://github.com                 |
-   |          |           |     |     |     |     |     |   .. _my blog: http://www.worldhello.net        | .. _my blog: http://www.worldhello.net        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     | ttl |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 访问 "Google (Search)":https://google.com   | - 访问 `Google `__        |
-   |          |           |     |     |     |     |     |   - 访问 "GitHub (Git host)":github             | - 访问 `GitHub`_                              |
-   |          |           |     |     |     |     |     |   - 访问 "WorldHello":wh                        | - 访问 `WorldHello`_                          |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   [github]http://github.com                     | .. _GitHub: http://github.com                 |
-   |          |           |     |     |     |     |     |   [wh]http://www.worldhello.net                 | .. _WorldHello: http://www.worldhello.net     |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     | asc |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 访问 http://google.com[Google]              | - 访问 `Google `__         |
-   |          |           |     |     |     |     |     |   - 访问 link:/index.html[首页]                 | - 访问 `首页 `__                 |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     |     | org | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 访问 [[http://google.com][Google]]          | - 访问 `Google `__         |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          | 内部跳转  | md  |     |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |          | .. _md-anchor:                                |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   跳转至 [文内链接](#md-anchor) 。              | 跳转至 `文内链接 <#md-anchor>`__ 。           |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     | rst |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   .. _fig1:                                     | .. _fig1:                                     |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   .. figure:: /images/github.png                | .. figure:: /images/github.png                |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |      内部跳转图例                               |    内部跳转图例                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   上面定义的位置,可以:                        | 上面定义的位置,可以:                        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 通过 fig1_ 跳转。                           | - 通过 fig1_ 跳转。                           |
-   |          |           |     |     |     |     |     |   - 或者 `点击这里 <#fig1>`__ 跳转。            | - 或者 `点击这里 <#fig1>`__ 跳转。            |
-   |          |           |     |     |     |     |     |   - 或者参见 :ref:`fig1`\ 。                    | - 或者参见 :ref:`fig1`\ 。                    |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     | ttl |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |        | .. _ttl-anchor:                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   跳转至 "文内链接":#ttl-anchor 。              | 跳转至 `文内链接 <#ttl-anchor>`__ 。          |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     | asc |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   两种方式在这儿定义内部链接。                  | 两种方式在这儿定义内部链接。                  |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   [[alink1,链接标题1]]                          | .. _alink1:                                   |
-   |          |           |     |     |     |     |     |   anchor:alink2[链接标题2]                      | .. _alink2:                                   |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   指向位置:                                    | 指向位置:                                    |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 跳转至 <>                 | - 跳转至 `内部链接1 <#alink1>`__              |
-   |          |           |     |     |     |     |     |   - 跳转至 xref:alink2[]                        | - 跳转至 `链接标题2 <#alink2>`__              |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     |     | org | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   # <>                              | .. _org-anchor:                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   跳转至 [[#org-anchor][文内链接]]              | 跳转至 `文内链接 <#org-anchor>`__ 。          |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          | GitHub\   | gfm |     |     |     |     | ::                                              |                                               |
-   |          | 提交和\   |     |     |     |     |     |                                                 |                                               |
-   |          | 问题链接  |     |     |     |     |     |   指向同一提交的链接:                          | 指向同一提交的链接\ [#]_\ :                  |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 提交ID(SHA): cea00609ca8...               | - 提交ID(SHA): :ul:`cea00609ca8...`         |
-   |          |           |     |     |     |     |     |   - 用户@提交ID: mojombo@cea00609ca8...         | - 用户@提交ID: :ul:`mojombo@cea00609ca8...`   |
-   |          |           |     |     |     |     |     |   - 用户名/项目名@提交ID:                       | - 用户名/项目名@提交ID:                       |
-   |          |           |     |     |     |     |     |     mojombo/god@cea00609ca8...                  |   :ul:`mojombo/god@cea00609ca8...`            |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   指向同一Issue的链接:                         | 指向同一Issue的链接\ [#]_\ :                 |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - Issue编号: #1                               | - Issue编号: :ul:`#1`                         |
-   |          |           |     |     |     |     |     |   - 用户名及Issue编号: mojombo#1                | - 用户名及Issue编号: :ul:`mojombo#1`          |
-   |          |           |     |     |     |     |     |   - 用户名/项目名及Issue编号:                   | - 用户名/项目名及Issue编号:                   |
-   |          |           |     |     |     |     |     |     mojombo/god#1                               |   :ul:`mojombo/god#1`                         |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          | 脚注      |     | rst |     |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   reST脚注的多种表示法:                        | reST脚注的多种表示法:                        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 脚注即可以手动分配数字 [1]_ ,              | - 脚注即可以手动分配数字\ [1]_\ ,            |
-   |          |           |     |     |     |     |     |     也可以使用井号自动分配 [#]_ 。              |   也可以使用井号自动分配\ [2]_\ 。            |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 自动分配脚注 [#label]_ 也可以用             | - 自动分配脚注\ [#label]_\ 也可以用\          |
-   |          |           |     |     |     |     |     |     添加标签形式 [#label]_ 多次引用。           |   添加标签形式\ [#label]_\ 多次引用。         |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 还支持用星号嵌入符号式脚注,                | - 还支持用星号嵌入符号式脚注,                |
-   |          |           |     |     |     |     |     |     如这个 [*]_ 和 这个 [*]_ 。                 |   如这个\ [*]_\ 和 这个\ [*]_\ 。             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 使用单词做标识亦可 [CIT2012]_ 。            | - 使用单词做标识亦可\ [CIT2012]_\ 。          |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   .. [1] 数字编号脚注。                         | .. [1] 数字编号脚注。                         |
-   |          |           |     |     |     |     |     |   .. [#] 井号自动编号。                         | .. [2] 井号自动编号。                         |
-   |          |           |     |     |     |     |     |   .. [#label] 井号添加标签以便多次引用。        | .. [#label] 井号添加标签以便多次引用。        |
-   |          |           |     |     |     |     |     |   .. [*] 星号自动用符号做脚注标记。             | .. [*] 星号自动用符号做脚注标记。             |
-   |          |           |     |     |     |     |     |   .. [*] 星号自动用符号做脚注标记。             | .. [*] 星号自动用符号做脚注标记。             |
-   |          |           |     |     |     |     |     |   .. [CIT2012] 单词或其他规定格式。             | .. [CIT2012] 单词或其他规定格式。             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     | ttl |     |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   Textile是Redmine [4] 内置的标记语言。         | Textile是Redmine [4]_ 内置的标记语言。        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   fn4. http://goo.gl/rGyvs                      | .. [4] http://goo.gl/rGyvs                    |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     | asc |     | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   - 内联方式 footnote:[此处定义] 定义的脚注。   | - 内联方式 [5]_ 定义的脚注。                  |
-   |          |           |     |     |     |     |     |   - 定义脚注时可用一个ID标记                    | - 定义脚注时可用一个ID标记 [6]_ 。            |
-   |          |           |     |     |     |     |     |     footnoteref:[note6, 可多次引用] 。          | - 引用已定义的脚注 [6]_ 。                    |
-   |          |           |     |     |     |     |     |   - 引用已定义的脚注 footnoteref:[note6] 。     |                                               |
-   |          |           |     |     |     |     |     |                                                 | .. [5] 此处定义                               |
-   |          |           |     |     |     |     |     |                                                 | .. [6] 可多次引用                             |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |          |           |     |     |     |     | org | ::                                              |                                               |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   Twitter widget in Org homepage[fn:org]        | Twitter widget in Org homepage [7]_           |
-   |          |           |     |     |     |     |     |   cannot be accessed in Mainland China, which   | cannot be accessed in Mainland China, which   |
-   |          |           |     |     |     |     |     |   caused the homepage load very slowly. >:[     | caused the homepage load very slowly. >:[     |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   [fn:org] The link is: http://orgmode.org      | .. [7] The link is: http://orgmode.org        |
-   |          |           |     |     |     |     |     |                                                 |                                               |
-   +----------+-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   | 图片                 | md  |     |     |     |     | ::                                              |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   ![GitHub](/images/github.png "Logo")          | .. image:: /images/github.png                 |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   GitHub Logo: ![GitHub][logo]                  | GitHub Logo: |logo|                           |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   [logo]: /images/github.png "Logo"             | .. |logo| image:: /images/github.png          |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     | rst |     |     |     | ::                                              |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |    .. figure:: /images/github.png               | .. figure:: /images/github.png                |
-   |                      |     |     |     |     |     |       :width: 32                                |    :width: 32                                 |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |       图:GitHub Octocat                        |    图:GitHub Octocat                         |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |    - GitHub Logo: |octocat|                     | - GitHub Logo: |octocat|                      |
-   |                      |     |     |     |     |     |    - 带链接的图片:                             | - 带链接的图片:                              |
-   |                      |     |     |     |     |     |      |imglink|_                                 |   |imglink|_                                  |
-   |                      |     |     |     |     |     |    - 下图向右浮动。                             | - 下图向右浮动。                              |
-   |                      |     |     |     |     |     |       .. image:: /images/github.png             |    .. image:: /images/github.png              |
-   |                      |     |     |     |     |     |          :align: right                          |       :align: right                           |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |    .. |octocat| image:: /images/github.png      | .. |octocat| image:: /images/github.png       |
-   |                      |     |     |     |     |     |    .. |imglink| image:: /images/github.png      | .. |imglink| image:: /images/github.png       |
-   |                      |     |     |     |     |     |    .. _imglink: https://github.com/             | .. _imglink: https://github.com/              |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     |     | ttl |     |     | ::                                              |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   - GitHub Logo: !/images/github.png(Logo)!     | - GitHub Logo: |icon|                         |
-   |                      |     |     |     |     |     |   - 带链接的图片:                              | - 带链接的图片:                              |
-   |                      |     |     |     |     |     |     !/images/github.png!:https://github.com/    |   |imglink2|_                                 |
-   |                      |     |     |     |     |     |   - 下图向右浮动。                              | - 下图向右浮动。                              |
-   |                      |     |     |     |     |     |     !>/images/github.png!                       |    .. image:: /images/github.png              |
-   |                      |     |     |     |     |     |                                                 |       :align: right                           |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |                                                 | .. |icon| image:: /images/github.png          |
-   |                      |     |     |     |     |     |                                                 | .. |imglink2| image:: /images/github.png      |
-   |                      |     |     |     |     |     |                                                 | .. _imglink2: https://github.com/             |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     |     |     | asc |     | ::                                              |                                               |
-   |                      |     |     |     |     |     |                                                 | .. figure:: /images/github.png                |
-   |                      |     |     |     |     |     |   .GitHub Octocat                               |    :width: 32                                 |
-   |                      |     |     |     |     |     |   image::/images/github.png["Logo",width=32]    |                                               |
-   |                      |     |     |     |     |     |                                                 |    图:GitHub Octocat                         |
-   |                      |     |     |     |     |     |   - GitHub Logo:                                |                                               |
-   |                      |     |     |     |     |     |     image:/images/github.png["Logo"]            | - GitHub Logo: |ascimg|                       |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |                                                 | .. |ascimg| image:: /images/github.png        |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     |     |     |     | org | ::                                              |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   - GitHub Logo: [[file:/images/github.png]]    | - GitHub Logo: |orgimg|                       |
-   |                      |     |     |     |     |     |   - 带链接的图片:                              | - 带链接的图片:                              |
-   |                      |     |     |     |     |     |     [[https://github.com/][file:/images/...]]   |   |orgimglink|_                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |                                                 | .. |orgimg| image:: /images/github.png        |
-   |                      |     |     |     |     |     |                                                 | .. |orgimglink| image:: /images/github.png    |
-   |                      |     |     |     |     |     |                                                 | .. _orgimglink: https://github.com/           |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   +----------------------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   | 表格                 | gfm |     |     |     |     | ::                                              |  .. table::                                   |
-   |                      |     |     |     |     |     |                                                 |     :class: classic                           |
-   |                      |     |     |     |     |     |   head1 | head2  | head2                        |                                               |
-   |                      |     |     |     |     |     |   ------|:------:|------:                       |     +--------+--------+--------+              |
-   |                      |     |     |     |     |     |   left  | center | right                        |     | head1  | head2  | head3  |              |
-   |                      |     |     |     |     |     |   left  | center | right                        |     +========+========+========+              |
-   |                      |     |     |     |     |     |                                                 |     | left   | center | right  |              |
-   |                      |     |     |     |     |     |                                                 |     +--------+--------+--------+              |
-   |                      |     |     |     |     |     |                                                 |     | left   | center | right  |              |
-   |                      |     |     |     |     |     |                                                 |     +--------+--------+--------+              |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     | rst |     |     |     | ::                                              |                                               |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   .. table:: 示例表格                           | .. table:: 示例表格                           |
-   |                      |     |     |     |     |     |      :class: classic                            |    :class: classic                            |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |      +---------+--------+--------+              |    +---------+--------+--------+              |
-   |                      |     |     |     |     |     |      | head1   | head2  | head3  |              |    | head1   | head2  | head3  |              |
-   |                      |     |     |     |     |     |      +=========+========+========+              |    +=========+========+========+              |
-   |                      |     |     |     |     |     |      |         | cell   | cell   |              |    |         | cell   | cell   |              |
-   |                      |     |     |     |     |     |      | rowspan +--------+--------+              |    | rowspan +--------+--------+              |
-   |                      |     |     |     |     |     |      |         | * colspan       |              |    |         | * colspan       |              |
-   |                      |     |     |     |     |     |      |         | * another line  |              |    |         | * another line  |              |
-   |                      |     |     |     |     |     |      +---------+-----------------+              |    +---------+-----------------+              |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     |     | ttl |     |     | ::                                              | .. table:: 示例表格                           |
-   |                      |     |     |     |     |     |                                                 |    :class: classic                            |
-   |                      |     |     |     |     |     |   |_. head1 |_. head2 |_. head3 |               |                                               |
-   |                      |     |     |     |     |     |   |/3. rowspan | cell  | cell |                 |    +---------+--------+--------+              |
-   |                      |     |     |     |     |     |   |\2. colspan |                                |    | head1   | head2  | head3  |              |
-   |                      |     |     |     |     |     |   | cell | cell |                               |    +=========+========+========+              |
-   |                      |     |     |     |     |     |                                                 |    |         | cell   | cell   |              |
-   |                      |     |     |     |     |     |                                                 |    |         +--------+--------+              |
-   |                      |     |     |     |     |     |                                                 |    | rowspan |     colspan     |              |
-   |                      |     |     |     |     |     |                                                 |    |         +--------+--------+              |
-   |                      |     |     |     |     |     |                                                 |    |         | cell   | cell   |              |
-   |                      |     |     |     |     |     |                                                 |    +---------+-----------------+              |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     |     |     | asc |     | ::                                              | .. table::                                    |
-   |                      |     |     |     |     |     |                                                 |    :class: classic                            |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      |     |     |     |     |     |   [width="50%"]                                 |    +-----+-----+-----+-----+                  |
-   |                      |     |     |     |     |     |   |============================                 |    |  1  |  2  |  3  |  4  |                  |
-   |                      |     |     |     |     |     |   |1 |2 |3 |4                                   |    +-----+-----+-----+-----+                  |
-   |                      |     |     |     |     |     |   |5 2.2+|6 .3+|7                               |    |  5  |           |     |                  |
-   |                      |     |     |     |     |     |   |8                                            |    +-----+     6     |  7  |                  |
-   |                      |     |     |     |     |     |   |9 2+|10                                      |    |  8  |           |     |                  |
-   |                      |     |     |     |     |     |   |============================                 |    +-----+-----------+     |                  |
-   |                      |     |     |     |     |     |                                                 |    |  9  |    10     |     |                  |
-   |                      |     |     |     |     |     |                                                 |    +-----+-----------+-----+                  |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   |                      +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   |                      |     |     |     |     | org | ::                                              |  .. table:: 示例表格                          |
-   |                      |     |     |     |     |     |                                                 |     :class: classic                           |
-   |                      |     |     |     |     |     |   #+CAPTION: 示例表格                           |                                               |
-   |                      |     |     |     |     |     |   #+LABEL: tblref                               |     +--------+--------+--------+              |
-   |                      |     |     |     |     |     |      | head1 | head2 | head3 |                  |     | head1  | head2  | head3  |              |
-   |                      |     |     |     |     |     |      |-------+-------+-------|                  |     +========+========+========+              |
-   |                      |     |     |     |     |     |      | cell  | cell  | cell  |                  |     | cell   | cell   | cell   |              |
-   |                      |     |     |     |     |     |      | cell  | cell  | cell  |                  |     +--------+--------+--------+              |
-   |                      |     |     |     |     |     |                                                 |     | cell   | cell   | cell   |              |
-   |                      |     |     |     |     |     |                                                 |     +--------+--------+--------+              |
-   |                      |     |     |     |     |     |                                                 |                                               |
-   +----------+-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+
-   | 其他     | 混用\     | md  |     |     |     |     | ::                                              | 输出略。                                      |
-   |          | HTML      |     |     |     |     |     |                                                 |                                               |
-   |          |           |     |     |     |     |     |   
| | - | | | | | | | | HTML块中不能混用 **标记语法** | | - | | | | | | | |
| | - | | | | | | | | | | - | +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | | ttl | | | :: | 输出略。 | - | | | | | | | | | | - | | | | | | | |
| | - | | | | | | | | HTML块中可以混用 **标记语法** | | - | | | | | | | |
| | - | | | | | | | | | | - | +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | 转义 | | rst | | asc | | :: | | - | | | | | | | | | | - | | | | | | | | 反斜线作为转义字符,\ | 反斜线作为转义字符,\ | - | | | | | | | | 禁止对后面 \*字符* 做语法解析。 | 禁止对后面 \*字符* 做语法解析。 | - | | | | | | | | | | - | | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | | ttl | | | :: | | - | | | | | | | | | | - | | | | | | | | 用 notextile 标记的段落不进行语法解析。 | 用 notextile 标记的段落不进行语法解析。 | - | | | | | | | | | | - | | | | | | | | notextile. 不进行 *语法解析* 。 | 不进行 \*语法解析\* 。 | - | | | | | | | | | | - | +-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | 注释 | | rst | | | | :: | 无输出。 | - | | | | | | | | | | - | | | | | | | | .. 注释 | | - | | | | | | | | | | - | | | | | | | | .. | | - | | | | | | | | 缩进内容也是注释 | | - | | | | | | | | | | - | | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | | | asc | | :: | 无输出。 | - | | | | | | | | | | - | | | | | | | | ///////////////// | | - | | | | | | | | 四个或更多的斜线包围起来的 | | - | | | | | | | | 文字块是注释,被忽略。 | | - | | | | | | | | ///////////////// | | - | | | | | | | | | | - | | +-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - | | | | | | | org | :: | 无输出。 | - | | | | | | | | | | - | | | | | | | | # 行首井号是注释。 | | - | | | | | | | | | | - | | | | | | | | #+ 缩进行首用 ``#+`` 标记为注释。 | | - | | | | | | | | | | - | | | | | | | | | | - | | | | | | | | #+BEGIN_COMMENT | | - | | | | | | | | 块注释 | | - | | | | | | | | ... | | - | | | | | | | | #+END_COMMENT | | - | | | | | | | | | | - +----------+-----------+-----+-----+-----+-----+-----+-------------------------------------------------+-----------------------------------------------+ - -.. note:: - - 部分标记语言代号后添加了星标,代表该标记语言相应的语法实现稍有区别,\ - 或者GitHub的具体实现和标准有出入。 - - 为突出部分空格,使用符号 ``°`` 标记。 - ----- - -.. [#] Markdown是在Ruby应用中广泛使用的标记语言,语法简洁并可混用HTML。\ - 标准的Markdown语法缺乏如表格等关键特性的支持,虽然不同的解析器\ - 都对其语法进行了扩展,但实现各有不同,造成一定的混乱。\ - 网址:\ http://daringfireball.net/projects/markdown/\ 。 -.. [#] GitHub使用Redcarpet作为Markdown的解析工具,并添加了额外的语法扩展。\ - 网址:\ http://github.github.com/github-flavored-markdown/\ 。 -.. [#] reStructuredText可简写为reST或RST,是在Python中广泛使用的标记语言。\ - reST的语法简洁严谨,本书就是使用Sphinx扩展的reST语法和工具撰写的。\ - 网址:\ http://docutils.sourceforge.net/rst.html\ 。 -.. [#] Textile是在Ruby应用中广泛使用的标记语言,例如Redmine就将Textile\ - 作为内置的标记语言。\ - 网址:\ http://redcloth.org/textile\ 。 -.. [#] RDoc是内嵌于Ruby代码中用于维护软件文档的标记语言。\ - 网址:\ http://rdoc.sourceforge.net/doc/\ 。 -.. [#] POD是内嵌于Perl代码中用于维护软件文档的标记语言。\ - 网址:\ http://perldoc.perl.org/perlpod.html\ 。 -.. [#] Org-mode是Emacs的一种编辑模式,除文档外还被广泛应用于维护TODO列表、\ - 项目计划等。\ - 网址:\ http://orgmode.org/org.html\ 。 -.. [#] MediaWiki是著名的维基百科(WikiPedia)所使用的维基语言。\ - 网址:\ http://www.mediawiki.org/wiki/Help:Formatting\ 。 -.. [#] 维基的实现有上百种,语法各不相同。Creole试图建立统一的维基语法标准。\ - 网址:\ http://www.wikicreole.org/\ 。 -.. [#] DocBook是著名的用于文档撰写的标记语言,采用XML文件格式及大量的面向\ - 出版的格式标签,能够实现单一源文件出版(Single-Source Publishing),\ - 即一次撰写多种格式输出(Write once, publish many)。\ - 但复杂的XML标签给写作过程带来不小的负担。\ - 网址:\ http://www.docbook.org/\ 。 -.. [#] AsciiDoc的轻量级标签和DocBook的XML标签语法有着清晰的对应关系,\ - 既解决了DocBook语言标签复杂、难读难写的问题,又可利用DocBook\ - 丰富的工具链实现单一源文件向多种格式的输出转换。\ - 网址:\ http://www.methods.co.nz/asciidoc\ 。 -.. [#] https://github.com/mojombo/god/commit/cea00609ca8441c82bc9760ae5eea7d7509d85b3 -.. [#] https://github.com/mojombo/god/issues/1 diff --git a/conf.py b/conf.py index 421f6ce..9f7119a 100644 --- a/conf.py +++ b/conf.py @@ -41,16 +41,16 @@ # General information about the project. project = u'GotGitHub' -copyright = u'2011, 蒋鑫' +copyright = u'2011, Jiang Xin' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '0.9' +version = '0.1' # The full version, including alpha/beta/rc tags. -release = '0.9' +release = '0.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -104,7 +104,7 @@ # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -html_title = u'GotGitHub' +#html_title = None # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None @@ -215,5 +215,3 @@ ('index', 'gotgithub', u'GotGitHub Documentation', [u'Jiang Xin'], 1) ] - -language = 'zh_CN'; diff --git a/contrib/sphinx/0001-No-prefix-_-for-sphinx-build-output-directories.patch b/contrib/sphinx/0001-No-prefix-_-for-sphinx-build-output-directories.patch deleted file mode 100644 index 8b94fef..0000000 --- a/contrib/sphinx/0001-No-prefix-_-for-sphinx-build-output-directories.patch +++ /dev/null @@ -1,826 +0,0 @@ -From d83d125e3dadcd13b7cc95fba28e4036b4089b85 Mon Sep 17 00:00:00 2001 -Message-Id: -From: Jiang Xin -Date: Fri, 26 Aug 2011 10:39:23 +0800 -Subject: [PATCH] No prefix '_' for sphinx build output directories - -[This hack is based on sphinx 1.1.3.] - -Some phinx output dirs has a prefix such as '_static', '_sources', -'_images', '_downloads'. Because GitHub website host does not like -directories with a '_' prefix, and these paths are hard-coded (can -not be changed through config files), so comes this workaround. - -This patch change the hard-coded dirs from '_static', '_images', -'_sources', '_downloads' to 'static', 'images', 'sources', and -'downloads'. - -Signed-off-by: Jiang Xin ---- - doc/_templates/indexsidebar.html | 2 +- - doc/_templates/layout.html | 2 +- - doc/conf.py | 10 ++++---- - doc/config.rst | 6 ++--- - doc/templating.rst | 2 +- - sphinx/application.py | 4 +-- - sphinx/builders/html.py | 40 ++++++++++++++--------------- - sphinx/builders/htmlhelp.py | 2 +- - sphinx/builders/qthelp.py | 4 +-- - sphinx/builders/websupport.py | 10 ++++---- - sphinx/ext/graphviz.py | 2 +- - sphinx/ext/pngmath.py | 2 +- - sphinx/quickstart.py | 6 ++--- - sphinx/themes/agogo/layout.html | 4 +-- - sphinx/themes/basic/domainindex.html | 2 +- - sphinx/themes/basic/layout.html | 10 ++++---- - sphinx/themes/basic/search.html | 2 +- - sphinx/themes/basic/sourcelink.html | 2 +- - sphinx/themes/basic/static/searchtools.js_t | 2 +- - sphinx/themes/default/layout.html | 2 +- - sphinx/themes/haiku/layout.html | 8 +++--- - sphinx/themes/pyramid/layout.html | 4 +-- - sphinx/themes/pyramid/static/ie6.css | 2 +- - sphinx/themes/scrolls/layout.html | 4 +-- - sphinx/websupport/__init__.py | 2 +- - tests/root/_static/README | 1 - - tests/root/_static/excluded.css | 1 - - tests/root/_static/subdir/foo.css | 1 - - tests/root/conf.py | 2 +- - tests/root/static/README | 1 + - tests/root/static/excluded.css | 1 + - tests/root/static/subdir/foo.css | 1 + - tests/test_build_html.py | 24 ++++++++--------- - tests/test_quickstart.py | 11 +++++--- - 34 files changed, 91 insertions(+), 88 deletions(-) - delete mode 100644 tests/root/_static/README - delete mode 100644 tests/root/_static/excluded.css - delete mode 100644 tests/root/_static/subdir/foo.css - create mode 100644 tests/root/static/README - create mode 100644 tests/root/static/excluded.css - create mode 100644 tests/root/static/subdir/foo.css - -diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html -index feafd90..e3125f6 100644 ---- a/doc/_templates/indexsidebar.html -+++ b/doc/_templates/indexsidebar.html -@@ -1,5 +1,5 @@ - -+

- -

Download

- {% if version.endswith('(hg)') %} -diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html -index 6e609e1..d748c8a 100644 ---- a/doc/_templates/layout.html -+++ b/doc/_templates/layout.html -@@ -18,6 +18,6 @@ - - {% block header %} -
--Sphinx logo -+Sphinx logo -
- {% endblock %} -diff --git a/doc/conf.py b/doc/conf.py -index 1b8ba3e..f5c49b1 100644 ---- a/doc/conf.py -+++ b/doc/conf.py -@@ -20,7 +20,7 @@ show_authors = True - - html_theme = 'sphinxdoc' - modindex_common_prefix = ['sphinx.'] --html_static_path = ['_static'] -+html_static_path = ['static'] - html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']} - html_additional_pages = {'index': 'index.html'} - html_use_opensearch = 'http://sphinx.pocoo.org' -@@ -34,13 +34,13 @@ epub_publisher = 'http://sphinx.pocoo.org/' - epub_scheme = 'url' - epub_identifier = epub_publisher - epub_pre_files = [('index.html', 'Welcome')] --epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js', -- '_static/jquery.js', '_static/searchtools.js', '_static/underscore.js', -- '_static/basic.css', 'search.html'] -+epub_exclude_files = ['static/opensearch.xml', 'static/doctools.js', -+ 'static/jquery.js', 'static/searchtools.js', 'static/underscore.js', -+ 'static/basic.css', 'search.html'] - - latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation', - 'Georg Brandl', 'manual', 1)] --latex_logo = '_static/sphinx.png' -+latex_logo = 'static/sphinx.png' - latex_elements = { - 'fontpkg': '\\usepackage{palatino}', - } -diff --git a/doc/config.rst b/doc/config.rst -index 5d188c6..0da3f3a 100644 ---- a/doc/config.rst -+++ b/doc/config.rst -@@ -491,7 +491,7 @@ that use Sphinx' HTMLWriter class. - exceed 200 pixels. Default: ``None``. - - .. versionadded:: 0.4.1 -- The image file will be copied to the ``_static`` directory of the output -+ The image file will be copied to the ``static`` directory of the output - HTML, so an already existing file with that name will be overwritten. - - .. confval:: html_favicon -@@ -836,8 +836,8 @@ the `Dublin Core metadata `_. - template filename is empty, no html cover page is created. No cover at all - is created if the tuple is empty. Examples:: - -- epub_cover = ('_static/cover.png', 'epub-cover.html') -- epub_cover = ('_static/cover.png', '') -+ epub_cover = ('static/cover.png', 'epub-cover.html') -+ epub_cover = ('static/cover.png', '') - epub_cover = () - - The default value is ``()``. -diff --git a/doc/templating.rst b/doc/templating.rst -index 05a1346..1e24904 100644 ---- a/doc/templating.rst -+++ b/doc/templating.rst -@@ -198,7 +198,7 @@ Overriding works like this:: - - Add additional script files here, like this:: - -- {% set script_files = script_files + ["_static/myscript.js"] %} -+ {% set script_files = script_files + ["static/myscript.js"] %} - - .. data:: css_files - -diff --git a/sphinx/application.py b/sphinx/application.py -index bfb39a7..9d336bf 100644 ---- a/sphinx/application.py -+++ b/sphinx/application.py -@@ -467,7 +467,7 @@ class Sphinx(object): - StandaloneHTMLBuilder.script_files.append(filename) - else: - StandaloneHTMLBuilder.script_files.append( -- posixpath.join('_static', filename)) -+ posixpath.join('static', filename)) - - def add_stylesheet(self, filename): - from sphinx.builders.html import StandaloneHTMLBuilder -@@ -475,7 +475,7 @@ class Sphinx(object): - StandaloneHTMLBuilder.css_files.append(filename) - else: - StandaloneHTMLBuilder.css_files.append( -- posixpath.join('_static', filename)) -+ posixpath.join('static', filename)) - - def add_lexer(self, alias, lexer): - from sphinx.highlighting import lexers -diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py -index 8184037..1b38437 100644 ---- a/sphinx/builders/html.py -+++ b/sphinx/builders/html.py -@@ -71,8 +71,8 @@ class StandaloneHTMLBuilder(Builder): - embedded = False # for things like HTML help or Qt help: suppresses sidebar - - # This is a class attribute because it is mutated by Sphinx.add_javascript. -- script_files = ['_static/jquery.js', '_static/underscore.js', -- '_static/doctools.js'] -+ script_files = ['static/jquery.js', 'static/underscore.js', -+ 'static/doctools.js'] - # Dito for this one. - css_files = [] - -@@ -104,7 +104,7 @@ class StandaloneHTMLBuilder(Builder): - - if self.config.language is not None: - if self._get_translations_js(): -- self.script_files.append('_static/translations.js') -+ self.script_files.append('static/translations.js') - - def _get_translations_js(self): - candidates = [path.join(package_dir, 'locale', self.config.language, -@@ -412,9 +412,9 @@ class StandaloneHTMLBuilder(Builder): - doctree.settings = self.docsettings - - self.secnumbers = self.env.toc_secnumbers.get(docname, {}) -- self.imgpath = relative_uri(self.get_target_uri(docname), '_images') -+ self.imgpath = relative_uri(self.get_target_uri(docname), 'images') - self.post_process_images(doctree) -- self.dlpath = relative_uri(self.get_target_uri(docname), '_downloads') -+ self.dlpath = relative_uri(self.get_target_uri(docname), 'downloads') - self.current_docname = docname - self.docwriter.write(doctree, destination) - self.docwriter.assemble_parts() -@@ -452,7 +452,7 @@ class StandaloneHTMLBuilder(Builder): - - if self.config.html_use_opensearch and self.name != 'htmlhelp': - self.info(' opensearch', nonl=1) -- fn = path.join(self.outdir, '_static', 'opensearch.xml') -+ fn = path.join(self.outdir, 'static', 'opensearch.xml') - self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn) - - self.info() -@@ -507,13 +507,13 @@ class StandaloneHTMLBuilder(Builder): - def copy_image_files(self): - # copy image files - if self.images: -- ensuredir(path.join(self.outdir, '_images')) -+ ensuredir(path.join(self.outdir, 'images')) - for src in self.status_iterator(self.images, 'copying images... ', - brown, len(self.images)): - dest = self.images[src] - try: - copyfile(path.join(self.srcdir, src), -- path.join(self.outdir, '_images', dest)) -+ path.join(self.outdir, 'images', dest)) - except Exception, err: - self.warn('cannot copy image file %r: %s' % - (path.join(self.srcdir, src), err)) -@@ -521,14 +521,14 @@ class StandaloneHTMLBuilder(Builder): - def copy_download_files(self): - # copy downloadable files - if self.env.dlfiles: -- ensuredir(path.join(self.outdir, '_downloads')) -+ ensuredir(path.join(self.outdir, 'downloads')) - for src in self.status_iterator(self.env.dlfiles, - 'copying downloadable files... ', - brown, len(self.env.dlfiles)): - dest = self.env.dlfiles[src][1] - try: - copyfile(path.join(self.srcdir, src), -- path.join(self.outdir, '_downloads', dest)) -+ path.join(self.outdir, 'downloads', dest)) - except Exception, err: - self.warn('cannot copy downloadable file %r: %s' % - (path.join(self.srcdir, src), err)) -@@ -536,16 +536,16 @@ class StandaloneHTMLBuilder(Builder): - def copy_static_files(self): - # copy static files - self.info(bold('copying static files... '), nonl=True) -- ensuredir(path.join(self.outdir, '_static')) -+ ensuredir(path.join(self.outdir, 'static')) - # first, create pygments style file -- f = open(path.join(self.outdir, '_static', 'pygments.css'), 'w') -+ f = open(path.join(self.outdir, 'static', 'pygments.css'), 'w') - f.write(self.highlighter.get_stylesheet()) - f.close() - # then, copy translations JavaScript file - if self.config.language is not None: - jsfile = self._get_translations_js() - if jsfile: -- copyfile(jsfile, path.join(self.outdir, '_static', -+ copyfile(jsfile, path.join(self.outdir, 'static', - 'translations.js')) - - # add context items for search function used in searchtools.js_t -@@ -557,7 +557,7 @@ class StandaloneHTMLBuilder(Builder): - themeentries = [path.join(themepath, 'static') - for themepath in self.theme.get_dirchain()[::-1]] - for entry in themeentries: -- copy_static_entry(entry, path.join(self.outdir, '_static'), -+ copy_static_entry(entry, path.join(self.outdir, 'static'), - self, ctx) - # then, copy over all user-supplied static files - staticentries = [path.join(self.confdir, spath) -@@ -570,18 +570,18 @@ class StandaloneHTMLBuilder(Builder): - if not path.exists(entry): - self.warn('html_static_path entry %r does not exist' % entry) - continue -- copy_static_entry(entry, path.join(self.outdir, '_static'), self, -+ copy_static_entry(entry, path.join(self.outdir, 'static'), self, - ctx, exclude_matchers=matchers) - # copy logo and favicon files if not already in static path - if self.config.html_logo: - logobase = path.basename(self.config.html_logo) -- logotarget = path.join(self.outdir, '_static', logobase) -+ logotarget = path.join(self.outdir, 'static', logobase) - if not path.isfile(logotarget): - copyfile(path.join(self.confdir, self.config.html_logo), - logotarget) - if self.config.html_favicon: - iconbase = path.basename(self.config.html_favicon) -- icontarget = path.join(self.outdir, '_static', iconbase) -+ icontarget = path.join(self.outdir, 'static', iconbase) - if not path.isfile(icontarget): - copyfile(path.join(self.confdir, self.config.html_favicon), - icontarget) -@@ -746,7 +746,7 @@ class StandaloneHTMLBuilder(Builder): - self.warn("error writing file %s: %s" % (outfilename, err)) - if self.copysource and ctx.get('sourcename'): - # copy the source file for the "show source" link -- source_name = path.join(self.outdir, '_sources', -+ source_name = path.join(self.outdir, 'sources', - os_path(ctx['sourcename'])) - ensuredir(path.dirname(source_name)) - copyfile(self.env.doc2path(pagename), source_name) -@@ -930,7 +930,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): - - if self.config.html_use_opensearch: - self.info(' opensearch', nonl=1) -- fn = path.join(self.outdir, '_static', 'opensearch.xml') -+ fn = path.join(self.outdir, 'static', 'opensearch.xml') - self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn) - - self.info() -@@ -1003,7 +1003,7 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder): - # if there is a source file, copy the source file for the - # "show source" link - if ctx.get('sourcename'): -- source_name = path.join(self.outdir, '_sources', -+ source_name = path.join(self.outdir, 'sources', - os_path(ctx['sourcename'])) - ensuredir(path.dirname(source_name)) - copyfile(self.env.doc2path(pagename), source_name) -diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py -index fdf25cc..d122563 100644 ---- a/sphinx/builders/htmlhelp.py -+++ b/sphinx/builders/htmlhelp.py -@@ -212,7 +212,7 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder): - outdir += os.sep - olen = len(outdir) - for root, dirs, files in os.walk(outdir): -- staticdir = root.startswith(path.join(outdir, '_static')) -+ staticdir = root.startswith(path.join(outdir, 'static')) - for fn in files: - if (staticdir and not fn.endswith('.js')) or \ - fn.endswith('.html'): -diff --git a/sphinx/builders/qthelp.py b/sphinx/builders/qthelp.py -index 5e5deaf..f2fa13a 100644 ---- a/sphinx/builders/qthelp.py -+++ b/sphinx/builders/qthelp.py -@@ -155,8 +155,8 @@ class QtHelpBuilder(StandaloneHTMLBuilder): - outdir += os.sep - olen = len(outdir) - projectfiles = [] -- staticdir = path.join(outdir, '_static') -- imagesdir = path.join(outdir, '_images') -+ staticdir = path.join(outdir, 'static') -+ imagesdir = path.join(outdir, 'images') - for root, dirs, files in os.walk(outdir): - resourcedir = root.startswith(staticdir) or \ - root.startswith(imagesdir) -diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py -index b775730..f0a1135 100644 ---- a/sphinx/builders/websupport.py -+++ b/sphinx/builders/websupport.py -@@ -37,7 +37,7 @@ class WebSupportBuilder(PickleHTMLBuilder): - raise RuntimeError('websupport builder must be used with ' - 'the builtin templates') - # add our custom JS -- self.script_files.append('_static/websupport.js') -+ self.script_files.append('static/websupport.js') - - def set_webinfo(self, staticdir, virtual_staticdir, search, storage): - self.staticdir = staticdir -@@ -58,9 +58,9 @@ class WebSupportBuilder(PickleHTMLBuilder): - - self.cur_docname = docname - self.secnumbers = self.env.toc_secnumbers.get(docname, {}) -- self.imgpath = '/' + posixpath.join(self.virtual_staticdir, '_images') -+ self.imgpath = '/' + posixpath.join(self.virtual_staticdir, 'images') - self.post_process_images(doctree) -- self.dlpath = '/' + posixpath.join(self.virtual_staticdir, '_downloads') -+ self.dlpath = '/' + posixpath.join(self.virtual_staticdir, 'downloads') - self.docwriter.write(doctree, destination) - self.docwriter.assemble_parts() - body = self.docwriter.parts['fragment'] -@@ -129,7 +129,7 @@ class WebSupportBuilder(PickleHTMLBuilder): - # "show source" link - if ctx.get('sourcename'): - source_name = path.join(self.staticdir, -- '_sources', os_path(ctx['sourcename'])) -+ 'sources', os_path(ctx['sourcename'])) - ensuredir(path.dirname(source_name)) - copyfile(self.env.doc2path(pagename), source_name) - -@@ -142,7 +142,7 @@ class WebSupportBuilder(PickleHTMLBuilder): - PickleHTMLBuilder.handle_finish(self) - - # move static stuff over to separate directory -- directories = ['_images', '_static'] -+ directories = ['images', 'static'] - for directory in directories: - src = path.join(self.outdir, directory) - dst = path.join(self.staticdir, directory) -diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py -index ee93594..296cf0e 100644 ---- a/sphinx/ext/graphviz.py -+++ b/sphinx/ext/graphviz.py -@@ -128,7 +128,7 @@ def render_dot(self, code, options, format, prefix='graphviz'): - if hasattr(self.builder, 'imgpath'): - # HTML - relfn = posixpath.join(self.builder.imgpath, fname) -- outfn = path.join(self.builder.outdir, '_images', fname) -+ outfn = path.join(self.builder.outdir, 'images', fname) - else: - # LaTeX - relfn = fname -diff --git a/sphinx/ext/pngmath.py b/sphinx/ext/pngmath.py -index 78c331a..e391e4c 100644 ---- a/sphinx/ext/pngmath.py -+++ b/sphinx/ext/pngmath.py -@@ -78,7 +78,7 @@ def render_math(self, math): - - shasum = "%s.png" % sha(math.encode('utf-8')).hexdigest() - relfn = posixpath.join(self.builder.imgpath, 'math', shasum) -- outfn = path.join(self.builder.outdir, '_images', 'math', shasum) -+ outfn = path.join(self.builder.outdir, 'images', 'math', shasum) - if path.isfile(outfn): - depth = read_png_depth(outfn) - return relfn, depth -diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py -index 86dc047..4552e91 100644 ---- a/sphinx/quickstart.py -+++ b/sphinx/quickstart.py -@@ -160,7 +160,7 @@ html_theme = 'default' - # Add any paths that contain custom static files (such as style sheets) here, - # relative to this directory. They are copied after the builtin static files, - # so a file named "default.css" will overwrite the builtin "default.css". --html_static_path = ['%(dot)sstatic'] -+html_static_path = ['static'] - - # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, - # using the given strftime format. -@@ -852,7 +852,7 @@ Either, you use a directory "_build" within the root path, or you separate - if 'dot' not in d: - print ''' - Inside the root directory, two more directories will be created; "_templates" --for custom HTML templates and "_static" for custom stylesheets and other static -+for custom HTML templates and "static" for custom stylesheets and other static - files. You can enter another prefix (such as ".") to replace the underscore.''' - do_prompt(d, 'dot', 'Name prefix for templates and static dir', '_', ok) - -@@ -997,7 +997,7 @@ def generate(d, overwrite=True, silent=False): - d['exclude_patterns'] = repr(d['dot'] + 'build') - mkdir_p(builddir) - mkdir_p(path.join(srcdir, d['dot'] + 'templates')) -- mkdir_p(path.join(srcdir, d['dot'] + 'static')) -+ mkdir_p(path.join(srcdir, 'static')) - - def write_file(fpath, mode, content): - if overwrite or not path.isfile(fpath): -diff --git a/sphinx/themes/agogo/layout.html b/sphinx/themes/agogo/layout.html -index d063194..fd6d4a2 100644 ---- a/sphinx/themes/agogo/layout.html -+++ b/sphinx/themes/agogo/layout.html -@@ -15,7 +15,7 @@ -
- {%- if logo %} - - {%- endif %} - {%- block headertitle %} -@@ -75,7 +75,7 @@ - {%- endfor %} - {%- if show_source and has_source and sourcename %} -
-- {{ _('Show Source') }} - {%- endif %} -
-diff --git a/sphinx/themes/basic/domainindex.html b/sphinx/themes/basic/domainindex.html -index 947a01e..776c034 100644 ---- a/sphinx/themes/basic/domainindex.html -+++ b/sphinx/themes/basic/domainindex.html -@@ -39,7 +39,7 @@ - in entries %} - - {% if grouptype == 1 -%} -- - {%- endif %} - {% if grouptype == 2 %}   {% endif %} -diff --git a/sphinx/themes/basic/layout.html b/sphinx/themes/basic/layout.html -index 9fb989c..a00570e 100644 ---- a/sphinx/themes/basic/layout.html -+++ b/sphinx/themes/basic/layout.html -@@ -52,7 +52,7 @@ - {%- block sidebarlogo %} - {%- if logo %} - - {%- endif %} - {%- endblock %} -@@ -100,8 +100,8 @@ - {%- endmacro %} - - {%- macro css() %} -- -- -+ -+ - {%- for cssfile in css_files %} - - {%- endfor %} -@@ -120,10 +120,10 @@ - {%- if use_opensearch %} - -+ href="{{ pathto('static/opensearch.xml', 1) }}"/> - {%- endif %} - {%- if favicon %} -- -+ - {%- endif %} - {%- endif %} - {%- block linktags %} -diff --git a/sphinx/themes/basic/search.html b/sphinx/themes/basic/search.html -index 4cdc693..69a5b6e 100644 ---- a/sphinx/themes/basic/search.html -+++ b/sphinx/themes/basic/search.html -@@ -9,7 +9,7 @@ - #} - {% extends "layout.html" %} - {% set title = _('Search') %} --{% set script_files = script_files + ['_static/searchtools.js'] %} -+{% set script_files = script_files + ['static/searchtools.js'] %} - {% block extrahead %} -