diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..4f389067 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,37 @@ +# 向 Pro Git （第二版 简体中文）贡献 + + +## 许可 + +向本仓库开启一个拉取请求，意味着你同意在 [项目许可](LICENSE.asc) 下提供你的工作。 +同样，因为未来打印版本的需要，你同意以这种许可授权你的工作给 @ben 与 @schacon。 +你的修改可能会出现在一个印刷版本中，你将被包括在 [贡献者列表](book/contributors.asc)。 + +## 小的修正 + +如果我们同意勘误和基本说明会提升内容质量，那么它们将会被接受。你也可以打开一个 Issue 这样我们可以确定如何或者是否需要解决。 + +如果你之前从未这样做过，[流程向导](https://guides.github.com/introduction/flow/) 会很有用。 + +## 大范围重写 + +在你开始前打开一个 Issue 讨论一下。这些改动往往会非常主观，经常只会为一小部分人澄清事实，很少值得花时间来接受它们。专业的文字编辑已经审核这个内容多次，而你可能在品味和语法上比我们更好一些，你所写的内容不太可能 *如此* 的优秀以致于值得修改一大片文字。 + +## 图表 + +本书中使用的图片是使用 [Sketch 3](http://bohemiancoding.com/sketch/) 和 [包含的 sketchbook 文件](diagram-source/progit.sketch) 生成的。 + +添加一个图表： + +1. 向 sketchbook 添加一页。尽可能尝试使用内置符号。 +1. 向你的页中添加一个 "slice"。并给它一个相对于源代码根目录的与目标PNG文件名一致的名字。 +1. 确保你的 slice 设置导出为 "800w"。 + + +## 翻译 + +我们非常鼓励将本书翻译成其它语言，但是与第一版相比有一些区别。现在，我们将每一个翻译放在一个独立的仓库，通过 Atlas 自动构建输出文件。这与上一版非常不同。 + +由于每一个翻译都是不同的仓库，我们就能够为每一个项目指定不同的维护人员。Pro Git 团队只需要进行拉取操作，并为每一个翻译团队进行构建。为了进行自动构建，翻译的仓库需要添加到 [GitHub上的 `progit` 组织](https://github.com/progit)。 + +你可以在 http://progit.org/translations[] 找到所有当前翻译的信息以及如何开始你自己的翻译。 diff --git a/LICENSE.asc b/LICENSE.asc index 0514d928..81f2824e 100644 --- a/LICENSE.asc +++ b/LICENSE.asc @@ -1 +1 @@ -This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA. +This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. diff --git a/README.asc b/README.asc index 5c0c4047..6726a7f7 100644 --- a/README.asc +++ b/README.asc @@ -1,34 +1,29 @@ -= Pro Git，第二版，简体中文翻译 - -*在翻译之前，请务必阅读 TRANSLATION_NOTES* += Pro Git，第二版，简体中文 欢迎阅读 Pro Git 第二版。 你可以在以下地址找到本书的在线版本： http://git-scm.com/book -与第一版类似，Pro Git 第二版以知识共享协议开放源代码。 - -自第一版开源以来，许多事情都发生了改变。其一，我们将本书的文本由 Markdown 迁移至 Asciidoc。同时，我们还开始使用 O'Reilly 的 https://atlas.oreilly.com[Atlas平台]生成本书的持续构建，所以，所有主要格式在每种语言都是一致的。 +与第一版类似，Pro Git 第二版以知识共享协议开源。 -我们还在独立的资源库中进行翻译，而不是在英文资源库的子目录中。详见翻译部分。 - -== 贡献 +自第一版开源以来，许多事情都发生了改变。 +其一，我们将本书的文本由 Markdown 迁移至 Asciidoc。 +同时，我们还开始使用 O'Reilly 的 https://atlas.oreilly.com[Atlas平台] 持续构建生成本书，因此，所有主要格式在每种语言都是可用的。 -为向本资源库贡献勘误表或新的内容，你需要开启一个 GitHub 的 Pull Request。一般地，一个比较好的做法是，在进行任何大的改变之前，先开启一个问题（issue）并且确保你的工作能够被接受。 - -如果我们认为有助于内容的改进，勘误表和说明都会被接受。你也可以开启一个问题，以便我们能够找出如何或者这个问题是不是能够被定位。 - -请对那些彻底的内容审查修改保持克制，因为那些修改通常不会被接受，我们不希望浪费你的时间。这种修改通常非常主观，只能提供给少部分人阅读，接受它们并不值得。书中内容已经经过多次专业的内容审查，所以你可能有一些比我们更好的文风和语法，但是你的个人讨论不大可能比本文的阐述*好得多*，从而导致我们需要修改本书的大部分内容。 +我们还在独立的仓库中进行翻译，而不是在英文仓库的子目录中。 +查看链接：CONTRIBUTING.md[贡献文档] 了解更多信息。 == 如何生成本书 -有两种办法可以通过源代码生成电子书。 +有两种办法可以通过这份源代码生成电子书。 -最简单的办法是让我们去做这个工作。我们有一个机器人时刻准备着，寻找主分支上的新工作，为每个人自动构建。 +最简单的办法是让我们去做这个工作。 +我们有一个机器人时刻准备着，寻找主分支上的新工作，为每个人自动构建。 -你可以在 http://git-scm.com/book[]找到当前构建，详情请见 https://progit.org[]。 +你可以在 http://git-scm.com/book[] 找到当前构建，关于构建可用的详情请见 https://progit.org[]。 -另一个生成电子书文件的方法是使用 Asciidoctor 手动完成。如果你运行下面的命令，你_可能_获得 HTML、Epub、Mobi 和 PDF 输出文件： +另一个生成电子书文件的方法是使用 Asciidoctor 手动完成。 +如果你运行下面的命令，你 _可能_ 实际上获得 HTML、Epub、Mobi 和 PDF 输出文件： ---- $ bundle install @@ -44,22 +39,8 @@ Converting to PDF... -- PDF output at progit.pdf ---- -这些命令使用了`asciidoctor`、`asciidoctor-pdf`和`asciidoctor-epub`项目。 - -== 翻译 +这些命令使用了 `asciidoctor`、`asciidoctor-pdf` 和 `asciidoctor-epub` 项目。 -我们非常鼓励将本书翻译成其它语言，但是与第一版相比有一些区别。现在，我们将每一个翻译放在一个独立的资源库，通过 Atlas 自动构建输出文件。这与上一版非常不同。 - -由于每一个翻译都是不同的资源库，我们就能够为每一个项目指定不同的维护人员。Pro Git 团队只需要进行拉取操作，并且为每一个翻译团队进行构建。为了进行自动构建，翻译的资源库需要添加到 https://github.com/progit[GitHub上的progit组织]。 - -你可以在 http://progit.org/translations[]找到所有当前翻译的信息以及如何开始你自己的翻译。 - -== 图表 - -本书中的图表使用 http://bohemiancoding.com/sketch/[Sketch 3]生成， link:diagram-source/progit.sketch[包含sketchbook文件]。 - -添加图表: +== 贡献 -. 向sketchbook添加新页，尽可能使用已经包含的符号。 -. 向你的页面添加``切片''，并给它一个相对于源代码根目录的与目标PNG文件名一致的名字。 -. 确保你的切片以3x的尺寸导出。 +如果你想要帮助修改或者贡献翻译，看一看链接：CONTRIBUTING.md[贡献者指南]。 diff --git a/Rakefile b/Rakefile index e4303dab..a98de2cf 100644 --- a/Rakefile +++ b/Rakefile @@ -26,3 +26,5 @@ namespace :book do puts " -- PDF output at progit.pdf" end end + +task :default => "book:build" diff --git a/atlas.json b/atlas.json index a48cdb90..d66a60a3 100644 --- a/atlas.json +++ b/atlas.json @@ -33,7 +33,7 @@ "epub": { "index": true, "toc": true, - "epubcheck": false, + "epubcheck": true, "embedded_fonts": [ "fonts/DejaVuSerif.otf", "fonts/DejaVuSans-Bold.otf", diff --git a/book/07-git-tools/sections/notes.asc b/book/07-git-tools/sections/notes.asc deleted file mode 100644 index a3d5514c..00000000 --- a/book/07-git-tools/sections/notes.asc +++ /dev/null @@ -1,258 +0,0 @@ -[[_git_notes]] -=== Notes - -One of the cool things about Git is that it has strong cryptographic integrity. If you change any bit in the commit data or any of the files it keeps, all the checksums change, including the commit SHA and every commit SHA since that one. However, that means that in order to amend the commit in any way, for instance to add some comments on something or even sign off on a commit, you have to change the SHA of the commit itself. - -Wouldn't it be nice if you could add data to a commit without changing its SHA? For this purpose, Git has a mechanism called `git notes` to attach data to a commit without modifying the commit message itself. - -To add a note to a specific commit, you only need to run `git notes add [commit]`, like this: - -[source,console] ----- -$ git notes add HEAD ----- - -This will open up your editor to write your note message. You can also use the `-m` option to provide the note right on the command line: - -[source,console] ----- -$ git notes add -m 'I approve - Scott' master~1 ----- - -That will add a note to the first parent on the last commit on the master branch. Now, how to view these notes? The easiest way is with the `git log` command. - -[source,console] ----- -$ git log master -commit 0385bcc3bc66d1b1ec07346c237061574335c3b8 -Author: Ryan Tomayko -Date: Tue Jun 22 20:09:32 2010 -0700 - - yield to run block right before accepting connections - -commit 06ca03a20bb01203e2d6b8996e365f46cb6d59bd -Author: Ryan Tomayko -Date: Wed May 12 06:47:15 2010 -0700 - - no need to delete these header names now - -Notes: - I approve - Scott ----- - -You can see the notes appended automatically in the log output. You can only have one note per commit in a namespace though (I will explain namespaces in the next section), so if you want to add a note to that commit, you have to instead edit the existing one. You can either do this by running: - -[source,console] ----- -$ git notes edit master~1 ----- - -Which will open a text editor with the existing note so you can edit it: - -[source,console] ----- -I approve - Scott - -# -# Write/edit the notes for the following object: -# -# commit 06ca03a20bb01203e2d6b8996e365f46cb6d59bd -# Author: Ryan Tomayko -# Date: Wed May 12 06:47:15 2010 -0700 -# -# no need to delete these header names now -# -# kidgloves.rb | 2 -- -# 1 files changed, 0 insertions(+), 2 deletions(-) -~ -~ -~ -".git/NOTES_EDITMSG" 13L, 338C ----- - -If you just want to add something to the end of an existing note, you can run `git notes append SHA`. - -Finally, you can give it a file with the content you want to add as a note with the `-F` flag. This could be useful for adding larger pieces of content to commits, perhaps emails or build output. - -=== Notes Namespaces - -Since you can only have one note per commit, Git allows you to have multiple namespaces for your notes. The default namespace is called ``commits'', but you can change that. Let's say we're using the ``commits'' notes namespace to store general comments but we want to also store bugzilla information for our commits. We can also have a ``bugzilla'' namespace. Here is how we would add a bug number to a commit under the bugzilla namespace: - -[source,console] ----- -$ git notes --ref=bugzilla add -m 'bug #15' 0385bcc3 ----- - -However, now you have to tell Git to specifically look in that namespace with the `--notes` flag: - -[source,console] ----- -$ git log --notes=bugzilla -commit 0385bcc3bc66d1b1ec07346c237061574335c3b8 -Author: Ryan Tomayko -Date: Tue Jun 22 20:09:32 2010 -0700 - - yield to run block right before accepting connections - -Notes (bugzilla): - bug #15 - -commit 06ca03a20bb01203e2d6b8996e365f46cb6d59bd -Author: Ryan Tomayko -Date: Wed May 12 06:47:15 2010 -0700 - - no need to delete these header names now - ----- - -Notice that it will only show notes from the namespace you designate. You can pass the option multiple times to see notes from multiple namespaces. You can also have it show notes from all your namespaces by running `git log --notes=*`. Here is what your log output might look like if you have a number of notes namespaces: - -[source,console] ----- -$ git log -1 --notes=* -commit 0385bcc3bc66d1b1ec07346c237061574335c3b8 -Author: Ryan Tomayko -Date: Tue Jun 22 20:09:32 2010 -0700 - - yield to run block right before accepting connections - -Notes: - I approve of this, too - Scott - -Notes (bugzilla): - bug #15 - -Notes (build): - build successful (8/13/10) ----- - -You can also switch the current namespace you're using so that the default for writing and showing notes is not 'commits' but, say, 'bugzilla' instead. This is done with the `core.notesRef` configuration variable. For instance you could run this to change the default: - -[source,console] ----- -$ git config core.notesRef refs/notes/bugzilla ----- - -[[_sharing_notes]] -=== Sharing Notes - -The notes (as you may have noticed in the previous section) are stored as references, just like branches and tags. This means you can push them to a server. However, Git has a bit of magic built in to expand a branch name like `master` to it's full name, which is `refs/heads/master`. Unfortunately, Git has no such magic built in for notes. So to push your notes to a server you cannot simply run something like `git push origin bugzilla`. Git will do -this: - -[source,console] ----- -$ git push origin bugzilla -error: src refspec bugzilla does not match any. -error: failed to push some refs to 'https://github.com/schacon/kidgloves' ----- - -However, you can push anything under `refs/` to a server, you just need to be more explicit about it. If you run this it will work fine: - -[source,console] ----- -$ git push origin refs/notes/bugzilla -Counting objects: 3, done. -Delta compression using up to 2 threads. -Compressing objects: 100% (2/2), done. -Writing objects: 100% (3/3), 263 bytes, done. -Total 3 (delta 0), reused 0 (delta 0) -To https://github.com/schacon/kidgloves - * [new branch] refs/notes/bugzilla -> refs/notes/bugzilla ----- - -In fact, you may want to just make that `git push origin refs/notes/*` which will push all your notes. This is what Git does normally for something like tags. When you run `git push origin --tags` it basically expands to `git push origin refs/tags/*`. - -[[_getting_notes]] -==== Getting Notes - -Unfortunately, getting notes is even more difficult. Notes do not come down with a clone and there nothing like `git fetch --notes`. In order to fetch notes, you have to specify both sides of the refspec. - -[source,console] ----- -$ git fetch origin refs/notes/*:refs/notes/* -remote: Counting objects: 12, done. -remote: Compressing objects: 100% (8/8), done. -remote: Total 12 (delta 0), reused 0 (delta 0) -Unpacking objects: 100% (12/12), done. -From github.com:schacon/kidgloves - * [new branch] refs/notes/bugzilla -> refs/notes/bugzilla ----- - -That is basically the only way to get them into your repository from the server. What is probably more common is to setup your Git config file to automatically pull them down when you fetch. If you look at your `.git/config` file you should have a section that looks like this: - -[source,console] ----- -[remote "origin"] - fetch = +refs/heads/*:refs/remotes/origin/* - url = https://github.com/schacon/kidgloves ----- - -The 'fetch' line is the refspec of what Git will try to do if you run just `git fetch origin`. It contains the magic formula of what Git will fetch and store local references to. For instance, in this case it will take every branch on the server and give you a local branch under 'remotes/origin/' so you can reference the 'master' branch on the server as 'remotes/origin/master' or just 'origin/master' (it will look under 'remotes' when it's trying to figure out what you're doing). If you change that line to `fetch = +refs/heads/*:refs/remotes/manamana/*` then even though your remote is named 'origin', the master branch from your 'origin' server will be under 'manamana/master'. - -You can use this to make your notes fetching easier. If you add multiple `fetch` lines, it will do them all. So in addition to the current `fetch` line, you can add a line that looks like this: - -[source,console] ----- -fetch = +refs/notes/*:refs/notes/* ----- - -Which says also get all the notes references on the server and store them as though they were local notes. - -=== Collaborating on Notes - -[source,console] ----- -[remote "origin"] - url = git@github.com:schacon/test.git - fetch = +refs/heads/*:refs/remotes/origin/* -[remote "notes"] - url = git@github.com:schacon/test.git - fetch = +refs/notes/*:refs/remote-notes/origin/* - push = refs/notes/*:refs/notes/* ----- - -[source,console] ----- -$ git push notes -Counting objects: 3, done. -Delta compression using up to 8 threads. -Compressing objects: 100% (2/2), done. -Writing objects: 100% (3/3), 267 bytes | 0 bytes/s, done. -Total 3 (delta 0), reused 0 (delta 0) -To git@github.com:schacon/test.git - * [new branch] refs/notes/commits -> refs/notes/commits ----- - -[source,console] ----- -$ git fetch notes -From github.com:schacon/test - * [new ref] refs/notes/commits -> refs/remote-notes/origin/commits ----- - -[source,console] ----- -$ git notes append -m 'my note' 1871649b61b87864c64bd0d7c9c2c88523968f6c ----- - -[source,console] ----- -$ git push notes -To git@github.com:schacon/test.git - ! [rejected] refs/notes/commits -> refs/notes/commits (non-fast-forward) -error: failed to push some refs to 'git@github.com:schacon/test.git' -hint: Updates were rejected because a pushed branch tip is behind its remote -hint: counterpart. Check out this branch and integrate the remote changes -hint: (e.g. 'git pull ...') before pushing again. -hint: See the 'Note about fast-forwards' in 'git push --help' for details. ----- - -[source,console] ----- -$ git notes merge refs/remote-notes/origin/commits -Fast-forward ----- - -TODO: I can't get `git notes merge` to work at all. May have to drop this section. - -So far, I've heard of people using them to have their ticketing system attach metadata automatically or have a system attach associated mailing list emails to commits they concern. Other people just use them entirely locally without pushing them anywhere to store reminders for themselves and whatnot. Probably a good start, but the ambitious among you may come up with something else interesting to do. Let me know! diff --git a/book/cover.png b/book/cover.png index a28c19e3..4dc57166 100644 Binary files a/book/cover.png and b/book/cover.png differ diff --git a/book/introduction.asc b/book/introduction.asc index 87a833f0..f74fe43a 100644 --- a/book/introduction.asc +++ b/book/introduction.asc @@ -36,7 +36,7 @@ *第十章*深入 Git 阴暗而漂亮的实现细节。现在，你已经知道所有有关 Git 的知识，能够熟练运用 Git 的强大优雅的功能。 接下来，你可以继续学习 Git 如何存储对象、Git 的对象模型是怎样的、打包文件的细节、服务器协议等更多知识。 -本书自始至终都将引用本章的内容，以便你能够在当时就可以深入了解。但是，如果你像我一样希望深入学习技术细节， +本书自始至终都将引用本章的内容，以便你能够在当时就可以深入了解。但是，如果你像我们一样希望深入学习技术细节， 你可能想先阅读第十章。我们将选择权交给你。 在*附录 A*，我们学习多个在特定环境中使用 Git 的实例。我们涵盖多个你可能会使用 Git 的多个 GUI 和 IDE 编程环境， diff --git a/diagram-source/progit.sketch b/diagram-source/progit.sketch index c2f27bbe..d866bbe6 100644 Binary files a/diagram-source/progit.sketch and b/diagram-source/progit.sketch differ diff --git a/status.json b/status.json index 9152d117..9cdfe0ad 100644 --- a/status.json +++ b/status.json @@ -1,7 +1,7 @@ { "code": "zh", "language": "Simplified Chinese", - "maintainers": ["devbean"], + "maintainers": ["networm"], "files": { "01-introduction": { "1-introduction.asc": 100, @@ -65,7 +65,6 @@ "sections/credentials.asc": 100, "sections/debugging.asc": 100, "sections/interactive-staging.asc": 100, - "sections/notes.asc": 100, "sections/replace.asc": 100, "sections/rerere.asc": 100, "sections/reset.asc": 100, diff --git a/theme/epub/layout.html b/theme/epub/layout.html new file mode 100644 index 00000000..e1e13b1a --- /dev/null +++ b/theme/epub/layout.html @@ -0,0 +1,14 @@ +{{ doctype }} + + + + + + + + {{ title }} + + + {{ content }} + + diff --git a/theme/pdf/pdf.xsl~ b/theme/pdf/pdf.xsl~ deleted file mode 100644 index a232cb3b..00000000 --- a/theme/pdf/pdf.xsl~ +++ /dev/null @@ -1,59 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file