Merge pull request #184 from networm/09-git-and-other-scms_import-custom

Translate 09-git-and-other-scms import-custom

Author: networm

book/09-git-and-other-scms/sections/import-custom.asc

@@ -1,18 +1,18 @@
 [[_custom_importer]]
-==== A Custom Importer
+==== 一个自定义的导入器
 
 (((git commands, fast-import)))
 (((Importing, from others)))
-If your system isn't one of the above, you should look for an importer online – quality importers are available for many other systems, including CVS, Clear Case, Visual Source Safe, even a directory of archives.
-If none of these tools works for you, you have a more obscure tool, or you otherwise need a more custom importing process, you should use `git fast-import`.
-This command reads simple instructions from stdin to write specific Git data.
-It's much easier to create Git objects this way than to run the raw Git commands or try to write the raw objects (see <<_git_internals>> for more information).
-This way, you can write an import script that reads the necessary information out of the system you're importing from and prints straightforward instructions to stdout.
-You can then run this program and pipe its output through `git fast-import`.
+如果你的系统不是上述中的任何一个，你需要在线查找一个导入器 - 针对许多其他系统有很多高质量的导入器，包括 CVS、Clear Case、Visual Source Safe，甚至是一个档案目录。
+如果没有一个工具适合你，需要一个不知名的工具，或者需要更大自由度的自定义导入过程，应当使用 `git fast-import`。
+这个命令从标准输入中读取简单指令来写入特定的 Git 数据。
+通过这种方式创建 Git 对象比运行原始 Git 命令或直接写入原始对象（查看 <<_git_internals>> 了解更多内容）更容易些。
+通过这种方式你可以编写导入脚本，从你要导入的系统中读取必要数据，然后直接打印指令到标准输出。
+然后可以运行这个程序并通过 `git fast-import` 重定向管道输出。
 
-To quickly demonstrate, you'll write a simple importer.
-Suppose you work in `current`, you back up your project by occasionally copying the directory into a time-stamped `back_YYYY_MM_DD` backup directory, and you want to import this into Git.
-Your directory structure looks like this:
+为了快速演示，我们会写一个简单的导入器。
+假设你在 `current` 工作，有时候会备份你的项目到时间标签 `back_YYYY_MM_DD` 备份目录中，你想要将这些导入到 Git 中。
+目录结构看起来是这样：
 
 [source,console]
 ----
@@ -24,18 +24,18 @@ back_2014_02_03
 current
 ----
 
-In order to import a Git directory, you need to review how Git stores its data.
-As you may remember, Git is fundamentally a linked list of commit objects that point to a snapshot of content.
-All you have to do is tell `fast-import` what the content snapshots are, what commit data points to them, and the order they go in.
-Your strategy will be to go through the snapshots one at a time and create commits with the contents of each directory, linking each commit back to the previous one.
+为了导入一个 Git 目录，需要了解 Git 如何存储它的数据。
+你可能记得，Git 在底层存储指向内容快照的提交对象的链表。
+所有要做的就是告诉 `fast-import` 哪些内容是快照，哪个提交数据指向它们，以及它们进入的顺序。
+你的策略是一次访问一个快照，然后用每个目录中的内容创建提交，并且将每一个提交与前一个连接起来。
 
-As we did in <<_an_example_git_enforced_policy>>, we'll write this in Ruby, because it's what we generally work with and it tends to be easy to read.
-You can write this example pretty easily in anything you're familiar with – it just needs to print the appropriate information to `stdout`.
-And, if you are running on Windows, this means you'll need to take special care to not introduce carriage returns at the end your lines – git fast-import is very particular about just wanting line feeds (LF) not the carriage return line feeds (CRLF) that Windows uses.
+如同我们在 <<_an_example_git_enforced_policy>> 里做的，我们将会使用 Ruby 写这个，因为它是我们平常工作中使用的并且它很容易读懂。
+可以使用任何你熟悉的东西来非常轻松地写这个例子 - 它只需要将合适的信息打印到 `标准输出`。
+然而，如果你在 Windows 上，这意味着需要特别注意不要引入回车符到行尾 - git fast-import 非常特别地只接受换行符（LF）而不是 Windows 使用的回车换行符（CRLF）。
 
-To begin, you'll change into the target directory and identify every subdirectory, each of which is a snapshot that you want to import as a commit.
-You'll change into each subdirectory and print the commands necessary to export it.
-Your basic main loop looks like this:
+现在开始，需要进入目标目录中并识别每一个子目录，每一个都是你要导入为提交的快照。
+要进入到每个子目录中并为导出它打印必要的命令。
+基本主循环像这个样子：
 
 [source,ruby]
 ----
@@ -54,17 +54,17 @@ Dir.chdir(ARGV[0]) do
 end
 ----
 
-You run `print_export` inside each directory, which takes the manifest and mark of the previous snapshot and returns the manifest and mark of this one; that way, you can link them properly.
-``Mark'' is the `fast-import` term for an identifier you give to a commit; as you create commits, you give each one a mark that you can use to link to it from other commits.
-So, the first thing to do in your `print_export` method is generate a mark from the directory name:
+在每个目录内运行 `print_export`，将会拿到清单并标记之前的快照，然后返回清单并标记现在的快照；通过这种方式，可以将它们合适地连接在一起。
+``标记'' 是一个给提交标识符的 `fast-import` 术语；当你创建提交，为每一个提交赋予一个标记来将它与其他提交连接在一起。
+这样，在你的 `print_export` 方法中第一件要做的事就是从目录名字生成一个标记：
 
 [source,ruby]
 ----
 mark = convert_dir_to_mark(dir)
 ----
 
-You'll do this by creating an array of directories and using the index value as the mark, because a mark must be an integer.
-Your method looks like this:
+可以创建一个目录的数组并使用索引做为标记，因为标记必须是一个整数。
+方法类似这样：
 
 [source,ruby]
 ----
@@ -77,16 +77,16 @@ def convert_dir_to_mark(dir)
 end
 ----
 
-Now that you have an integer representation of your commit, you need a date for the commit metadata.
-Because the date is expressed in the name of the directory, you'll parse it out.
-The next line in your `print_export` file is
+既然有一个整数代表你的提交，那还要给提交元数据一个日期。
+因为目录名字表达了日期，所以你将会从中解析出日期。
+你的 `print_export` 文件的下一行是
 
 [source,ruby]
 ----
 date = convert_dir_to_date(dir)
 ----
 
-where `convert_dir_to_date` is defined as
+`convert_dir_to_date` 定义为
 
 [source,ruby]
 ----
@@ -101,17 +101,17 @@ def convert_dir_to_date(dir)
 end
 ----
 
-That returns an integer value for the date of each directory.
-The last piece of meta-information you need for each commit is the committer data, which you hardcode in a global variable:
+那会返回每一个目录日期的整数。
+最后一项每个提交需要的元数据是提交者信息，它将会被硬编码在全局变量中：
 
 [source,ruby]
 ----
 $author = 'John Doe <[email protected]>'
 ----
 
-Now you're ready to begin printing out the commit data for your importer.
-The initial information states that you're defining a commit object and what branch it's on, followed by the mark you've generated, the committer information and commit message, and then the previous commit, if any.
-The code looks like this:
+现在准备开始为你的导入器打印出提交数据。
+初始信息声明定义了一个提交对象与它所在的分支，紧接着一个你生成的标记、提交者信息与提交信息、然后是一个之前的提交，如果它存在的话。
+代码看起来像这样：
 
 [source,ruby]
 ----
@@ -123,17 +123,17 @@ export_data('imported from ' + dir)
 puts 'from :' + last_mark if last_mark
 ----
 
-You hardcode the time zone (-0700) because doing so is easy.
-If you're importing from another system, you must specify the time zone as an offset.
-The commit message must be expressed in a special format:
+我们将硬编码时区信息（-0700），因为这样很容易。
+如果从其他系统导入，必须指定为一个偏移的时区。
+提交信息必须指定为特殊的格式：
 
 [source]
 ----
 data (size)\n(contents)
 ----
 
-The format consists of the word data, the size of the data to be read, a newline, and finally the data.
-Because you need to use the same format to specify the file contents later, you create a helper method, `export_data`:
+这个格式包括文本数据、将要读取数据的大小、一个换行符、最终的数据。
+因为之后还需要为文件内容指定相同的数据格式，你需要创建一个帮助函数，`export_data`：
 
 [source,ruby]
 ----
@@ -142,9 +142,9 @@ def export_data(string)
 end
 ----
 
-All that's left is to specify the file contents for each snapshot.
-This is easy, because you have each one in a directory – you can print out the `deleteall` command followed by the contents of each file in the directory.
-Git will then record each snapshot appropriately:
+剩下的工作就是指定每一个快照的文件内容。
+这很轻松，因为每一个目录都是一个快照 - 可以在目录中的每一个文件内容后打印 `deleteall` 命令。
+Git 将会适当地记录每一个快照：
 
 [source,ruby]
 ----
@@ -155,11 +155,11 @@ Dir.glob("**/*").each do |file|
 end
 ----
 
-Note:  Because many systems think of their revisions as changes from one commit to another, fast-import can also take commands with each commit to specify which files have been added, removed, or modified and what the new contents are.
-You could calculate the differences between snapshots and provide only this data, but doing so is more complex – you may as well give Git all the data and let it figure it out.
-If this is better suited to your data, check the `fast-import` man page for details about how to provide your data in this manner.
+注意：因为大多数系统认为他们的版本是从一个提交变化到另一个提交，fast-import 也可以为每一个提交执行命令来指定哪些文件是添加的、删除的或修改的与新内容是哪些。
+可以计算快照间的不同并只提供这些数据，但是这样做会很复杂 - 也可以把所有数据给 Git 然后让它为你指出来。
+如果这更适合你的数据，查阅 `fast-import` man 帮助页来了解如何以这种方式提供你的数据。
 
-The format for listing the new file contents or specifying a modified file with the new contents is as follows:
+这种列出新文件内容或用新内容指定修改文件的格式如同下面的内容：
 
 [source]
 ----
@@ -168,8 +168,8 @@ data (size)
 (file contents)
 ----
 
-Here, 644 is the mode (if you have executable files, you need to detect and specify 755 instead), and inline says you'll list the contents immediately after this line.
-Your `inline_data` method looks like this:
+这里，644 是模式（如果你有可执行文件，反而你需要检测并指定 755），inline 表示将会立即把内容放在本行之后。
+你的 `inline_data` 方法看起来像这样：
 
 [source,ruby]
 ----
@@ -180,9 +180,9 @@ def inline_data(file, code = 'M', mode = '644')
 end
 ----
 
-You reuse the `export_data` method you defined earlier, because it's the same as the way you specified your commit message data.
+可以重用之前定义的 `export_data` 方法，因为它与你定义的提交信息数据的方法一样。
 
-The last thing you need to do is to return the current mark so it can be passed to the next iteration:
+最后一件你需要做的是返回当前的标记以便它可以传给下一个迭代：
 
 [source,ruby]
 ----
@@ -191,18 +191,18 @@ return mark
 
 [NOTE]
 ====
-If you are running on Windows you'll need to make sure that you add one extra step.
-As mentioned before, Windows uses CRLF for new line characters while git fast-import expects only LF.
-To get around this problem and make git fast-import happy, you need to tell ruby to use LF instead of CRLF:
+如果在 Windows 上还需要确保增加一个额外步骤。
+正如之前提到的，Windows 使用 CRLF 作为换行符而 git fast-import 只接受 LF。
+为了修正这个问题使 git fast-import 正常工作，你需要告诉 ruby 使用 LF 代替 CRLF：
 
 [source,ruby]
 ----
 $stdout.binmode
 ----
 ====
 
-That's it.
-Here's the script in its entirety:
+就是这样。
+这是全部的脚本：
 
 
 [source,ruby]
@@ -274,7 +274,7 @@ Dir.chdir(ARGV[0]) do
 end
 ----
 
-If you run this script, you'll get content that looks something like this:
+如果运行这个脚本，你会得到类似下面的内容：
 
 [source,console]
 ----
@@ -304,8 +304,8 @@ M 644 inline README.md
 (...)
 ----
 
-To run the importer, pipe this output through `git fast-import` while in the Git directory you want to import into.
-You can create a new directory and then run `git init` in it for a starting point, and then run your script:
+为了运行导入器，将这些输出用管道重定向到你想要导入的 Git 目录中的 `git fast-import`。
+可以创建一个新的目录并在其中运行 `git init` 作为开始，然后运行你的脚本：
 
 [source,console]
 ----
@@ -337,9 +337,9 @@ pack_report: pack_mapped              =       1457 /       1457
 ---------------------------------------------------------------------
 ----
 
-As you can see, when it completes successfully, it gives you a bunch of statistics about what it accomplished.
-In this case, you imported 13 objects total for 4 commits into 1 branch.
-Now, you can run `git log` to see your new history:
+正如你所看到的，当它成功完成时，它会给你一串关于它完成内容的统计。
+这本例中，一共导入了 13 个对象、4 次提交到 1 个分支。
+现在，可以运行 `git log` 来看一下你的新历史：
 
 [source,console]
 ----
@@ -357,9 +357,9 @@ Date:   Mon Feb 3 01:00:00 2014 -0700
     imported from back_2014_02_03
 ----
 
-There you go – a nice, clean Git repository.
-It's important to note that nothing is checked out – you don't have any files in your working directory at first.
-To get them, you must reset your branch to where `master` is now:
+做得很好 - 一个漂亮、干净的 Git 仓库。
+要注意的一点是并没有检出任何东西 - 一开始你的工作目录内并没有任何文件。
+为了得到他们，你必须将分支重置到 `master` 所在的地方：
 
 [source,console]
 ----
@@ -370,5 +370,5 @@ $ ls
 README.md main.rb
 ----
 
-You can do a lot more with the `fast-import` tool – handle different modes, binary data, multiple branches and merging, tags, progress indicators, and more.
-A number of examples of more complex scenarios are available in the `contrib/fast-import` directory of the Git source code.
+可以通过 `fast-import` 工具做很多事情 - 处理不同模式、二进制数据、多个分支与合并、标签、进度指示等等。
+一些更复杂情形下的例子可以在 Git 源代码目录中的 `contrib/fast-import` 目录中找到。