commonmarker 0.0.1 → 0.1.0

data/test/benchmark.rb

@@ -1,4 +1,5 @@
 require 'commonmarker'
+require 'github/markdown'
 require 'redcarpet'
 require 'kramdown'
 require 'benchmark'
@@ -8,23 +9,26 @@ def dobench(name, &blk)
   puts Benchmark.measure(&blk)
 end
 
-benchinput = File.open('../CommonMark/bench/benchinput.md', 'r').read()
+benchinput = File.open('test/benchinput.md', 'r').read()
 
 printf("input size = %d bytes\n\n", benchinput.bytesize)
 
-dobench("commonmarker with to_html") do
-  CommonMarker::Node.parse_string(benchinput).to_html
+dobench('redcarpet') do
+  Redcarpet::Markdown.new(Redcarpet::Render::HTML, autolink: false, tables: false).render(benchinput)
 end
 
-dobench("commonmarker with ruby HtmlRenderer") do
-  CommonMarker::HtmlRenderer.new.render(CommonMarker::Node.parse_string(benchinput))
+dobench('github-markdown') do
+  GitHub::Markdown.render(benchinput)
 end
 
-dobench("redcarpet") do
-  Redcarpet::Markdown.new(Redcarpet::Render::HTML, autolink: false, tables: false).render(benchinput)
+dobench('commonmarker with to_html') do
+  CommonMarker::Node.parse_string(benchinput).to_html
 end
 
-dobench("kramdown") do
-  Kramdown::Document.new(benchinput).to_html(benchinput)
+dobench('commonmarker with ruby HtmlRenderer') do
+  CommonMarker::HtmlRenderer.new.render(CommonMarker::Node.parse_string(benchinput))
 end
 
+dobench('kramdown') do
+  Kramdown::Document.new(benchinput).to_html(benchinput)
+end

data/test/progit/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem 'maruku', '0.7.1'
+gem 'redcarpet'
+gem 'parallel'

data/test/progit/README.md

@@ -0,0 +1,9 @@
+# Pro Git, 1st Edition
+
+This is the source for the 1st edition of the Pro Git book. The second edition has since been released and is what will be maintained and published going forward. Please suggest any changes to that version instead. 
+
+You can find the new edition at:
+
+https://github.com/progit/progit2
+
+If you're looking for the original README content, it can be found in the [README.original.md](README.original.md) file.

data/test/progit/README.original.md

@@ -0,0 +1,70 @@
+[![Build Status](https://secure.travis-ci.org/progit/progit.png?branch=master)](https://travis-ci.org/progit/progit)
+
+# Pro Git Book Contents
+
+This is the source code for the Pro Git book contents.  It is licensed under
+the Creative Commons Attribution-Non Commercial-Share Alike 3.0 license.  I
+hope you enjoy it, I hope it helps you learn Git, and I hope you'll support
+Apress and me by purchasing a print copy of the book at Amazon:
+
+http://tinyurl.com/amazonprogit
+
+It is also available online at:
+
+http://git-scm.com/book/
+
+and fully translated in 10 languages.
+
+# Making Ebooks
+
+On Fedora (16 and later) you can run something like this::
+
+    $ yum install ruby calibre rubygems ruby-devel rubygem-ruby-debug rubygem-rdiscount
+    $ makeebooks en  # will produce a mobi
+
+On MacOS you can do like this:
+	
+1. INSTALL ruby and rubygems
+2. `$ gem install rdiscount`
+3. DOWNLOAD Calibre for MacOS and install command line tools. You'll need some dependencies to generate a PDF:
+    * pandoc: http://johnmacfarlane.net/pandoc/installing.html
+    * xelatex: http://tug.org/mactex/
+4. `$ makeebooks zh` #will produce a mobi
+
+On Windows you can do like this:
+	
+1. Install ruby and related tool from http://rubyinstaller.org/downloads/
+    * RubyInstaller (ruby & gem)
+    * Development Kit (to build rdiscount gem)
+2. Open `cmd` and `$ gem install rdiscount`
+3. Install Calibre for Windows from http://calibre-ebook.com/download
+4. `$ SET ebook_convert_path=c:\Program Files\Calibre2\ebook-convert.exe`. Modify to suit with your Calibre installed path.
+5. Make ebooks:
+    * `$ ruby makeebooks vi` #will produce a mobi
+    * `$ SET FORMAT=epub` then `$ ruby makeebooks vi` #will produce an epub
+
+## Notes on pandoc
+
+Please use Pandoc version 1.11.1 or later as older versions (confirmed on 1.9.1.1) has a [bug](https://github.com/jgm/pandoc/issues/964) which hides a word after tilde `~`.  You can do `pandoc -v` to see which version you have installed.
+
+# Errata
+
+If you see anything that is technically wrong or otherwise in need of
+correction, please [open an issue](https://github.com/progit/progit/issues/new) and one of the maintainers will take a look.
+
+
+# Translation
+
+If you wish to translate the book, your work will be put up on the 
+git-scm.com site.  Please put your translation into the appropriate
+subdirectory of this project, using the 
+[ISO 639](http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code 
+and send a pull request.
+
+# Sending a pull request
+
+* Be careful to use UTF-8 encoding in your files.
+* Do not mix changes to the original English with translations in a single pull request.
+* If your pull request changes a translation, prefix your pull request and commits' messages with the ISO 639 code, e.g. `[de] Update chapter 2`. Please only push files where there is already some translation done.
+* Make sure the translation changes can be automatically merged. The maintainers can not make the merge manually if there are some conflicts.
+* Make as sure as possible that the changes work correctly for publishing to PDF, ebooks and the git-scm.com website.

data/test/progit/Rakefile

@@ -0,0 +1,285 @@
+# encoding: UTF-8
+
+require 'rake/clean'
+require 'redcarpet'
+
+$lang = ENV['language']
+$lang ||= 'en'
+
+namespace :epub do
+	TMP_DIR = File.join('epub', 'temp', $lang)
+	INDEX_FILEPATH = File.join(TMP_DIR, 'progit.html')
+	TARGET_FILEPATH = "progit-#{$lang}.epub"
+	
+	SOURCE_FILES = FileList.new(File.join($lang, '0*', '*.markdown')).sort
+	CONVERTED_MK_FILES = SOURCE_FILES.pathmap(File.join(TMP_DIR, '%f'))
+	HTML_FILES = CONVERTED_MK_FILES.ext('html') 
+	
+	desc "generate EPUB ebook (add language=xx to build lang xx)"
+	task :generate => :check
+	task :generate => TARGET_FILEPATH
+	
+	desc "check whether all the required tools are installed"
+	task :check do
+		begin
+			require 'maruku'
+			found_maruku = true
+		rescue LoadError
+			found_maruku = false
+		end
+		
+		$ebook_convert_cmd = ENV['ebook_convert_path'].to_s
+		if $ebook_convert_cmd.empty?
+			$ebook_convert_cmd = `which ebook-convert`.chomp
+		end
+		if $ebook_convert_cmd.empty?
+			mac_osx_path = '/Applications/calibre.app/Contents/MacOS/ebook-convert'
+			$ebook_convert_cmd = mac_osx_path
+		end
+		found_calibre = File.executable?($ebook_convert_cmd)
+		
+		if !found_maruku
+			puts 'EPUB generation requires the Maruku gem.'
+			puts '  On Ubuntu call "sudo apt-get install libmaruku-ruby".'
+		end
+		if !found_calibre
+			puts 'EPUB generation requires Calibre.'
+			puts '  On Ubuntu call "sudo apt-get install calibre".'
+		end
+		
+		if !found_calibre || !found_maruku then exit 1 end
+	end
+	
+	directory TMP_DIR
+	
+	rule '.html' => '.mk' do |t|
+		require 'maruku'
+		
+		mk_filename = t.source
+		html_filename = t.name
+		puts "Converting #{mk_filename} -> #{html_filename}"
+		
+		mk_file = File.open(mk_filename, 'r') do |mk|
+			html_file = File.open(html_filename, 'w') do |html|
+				code = Maruku.new(mk.read.encode("UTF-8")).to_html
+				code.gsub!(/^(<h.) (id='[^']+?')/, '\1')
+				html << code
+				html << "\n"
+			end
+		end
+	end
+	
+	src_for_converted = proc do |dst|
+		base_name = dst.pathmap('%n')
+		SOURCE_FILES.find { |s| s.pathmap('%n') == base_name }
+	end
+	
+	rule '.mk' => src_for_converted do |t|
+		src_filename = t.source
+		dest_filename = t.name
+		puts "Processing #{src_filename} -> #{dest_filename}"
+		
+		figures_dir = "../../../figures"
+		
+		dest_file = File.open(dest_filename, 'w')
+		src_file = File.open(src_filename, 'r')
+		until src_file.eof?
+			line = src_file.readline
+			
+			matches = line.match /^\s*Insert\s(.*)/
+			if matches
+				image_path = matches[1]
+				real_image_path = image_path.pathmap("#{figures_dir}/%X-tn%x")
+				
+				next_line = src_file.readline.chomp
+				
+				line = "![#{next_line}](#{real_image_path} \"#{next_line}\")\n"
+			end
+			
+			dest_file << line
+		end
+		src_file.close
+		dest_file.close
+	end
+	
+	file INDEX_FILEPATH => TMP_DIR
+	file INDEX_FILEPATH => HTML_FILES do
+		index_file = File.open(INDEX_FILEPATH, 'w') do |file|
+			file << '<?xml version="1.0" encoding="UTF-8"?>'
+			file << "\n"
+			file << '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" '
+			file << '"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">'
+			file << "\n"
+			file << "<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='#{$lang}'>"
+			file << '<head>'
+			file << '<title>Pro Git - professional version control</title>'
+			file << '</head>'
+			file << '<body>'
+			file << "\n"
+			
+			HTML_FILES.each do |chapter_file|
+				file << File.open(chapter_file).read
+				file << "\n"
+			end
+			
+			file << '</body></html>'
+			file << "\n"
+		end
+	end
+	
+	file TARGET_FILEPATH => INDEX_FILEPATH do
+		opts = [
+			'--language', $lang,
+			'--authors', 'Scott Chacon',
+			'--comments', 'Licensed under the Creative Commons Attribution-Non Commercial-Share Alike 3.0 license',
+			
+			'--cover', 'epub/title.png',
+			'--extra-css', 'epub/ProGit.css',
+			
+			'--chapter', '//h:h1',
+			'--level1-toc', '//h:h1',
+			'--level2-toc', '//h:h2',
+			'--level3-toc', '//h:h3',
+		]
+		
+		sh $ebook_convert_cmd, INDEX_FILEPATH, TARGET_FILEPATH, *opts
+	end
+	
+	CLEAN.push(*CONVERTED_MK_FILES)
+	CLEAN.push(*HTML_FILES)
+	CLEAN << INDEX_FILEPATH
+	CLEAN << TMP_DIR
+	CLOBBER << TARGET_FILEPATH
+end
+
+namespace :pdf do
+        desc "generate a pdf"
+        task :generate  do
+                system("bash makepdfs")
+        end
+end
+
+class StderrDecorator
+  def initialize(out)
+    @out = out
+  end
+
+  def <<(x)
+    @out << "#{x}"
+    if x.match /REXML/
+      raise ""
+    end
+  end
+end
+
+def test_lang(lang, out)
+  error_code = false
+  chapter_figure = {
+    "01-introduction"       => 7,
+    "02-git-basics"         => 2,
+    "03-git-branching"      => 39,
+    "04-git-server"         => 15,
+    "05-distributed-git"    => 27,
+    "06-git-tools"          => 1,
+    "07-customizing-git"    => 3,
+    "08-git-and-other-scms" => 0,
+    "09-git-internals"      => 4}
+  source_files = FileList.new(File.join(lang, '0*', '*.markdown')).sort
+  source_files.each do |mk_filename|
+    src_file = File.open(mk_filename, 'r')
+    figure_count = 0
+    until src_file.eof?
+      line = src_file.readline
+      matches = line.match /^#/
+      if matches
+        if line.match /^(#+).*#[[:blank:]]+$/
+          out<< "\nBadly formatted title in #{mk_filename}: #{line}\n"
+          error_code = true
+        end
+      end
+      if line.match /^\s*Insert\s(.*)/i
+	if line.match /^\s*Insert\s(.*)/
+	  figure_count = figure_count + 1
+	else
+	  out << "\n#{lang}: Badly cased Insert directive: #{line}\n"
+	  error_code = true
+	end
+      end
+    end
+    # This extraction is a bit contorted, because the pl translation renamed
+    # the files, so the match is done on the directories.
+    tab_fig_count = chapter_figure[File.basename(File.dirname(mk_filename))]
+    expected_figure_count = tab_fig_count ? tab_fig_count:0
+    if figure_count > expected_figure_count
+      out << "\nToo many figures declared in #{mk_filename}\n"
+      error_code = true
+    end
+  end
+  begin
+    mark = (source_files.map{|mk_filename| File.open(mk_filename, 'r'){
+                |mk| mk.read.encode("UTF-8")}}).join("\n\n")
+    require 'maruku'
+    code = Maruku.new(mark, :on_error => :raise, :error_stream => StderrDecorator.new(out))
+  rescue
+    print $!
+    error_code = true
+  end
+  error_code
+end
+
+$out = $stdout
+
+namespace :ci do
+  desc "Parallel Continuous integration"
+  task :parallel_check do
+    require 'parallel'
+    langs = FileList.new('??')+FileList.new('??-??')
+    results = Parallel.map(langs) do |lang|
+      error_code = test_lang(lang, $out)
+      if error_code
+        print "processing #{lang} KO\n"
+      else
+        print "processing #{lang} OK\n"
+      end
+      error_code
+    end
+    fail "At least one language conversion failed" if results.any?
+  end
+
+  (FileList.new('??')+FileList.new('??-??')).each do |lang|
+    desc "testing " + lang
+    task (lang+"_check").to_sym do
+      error_code = test_lang(lang, $out)
+      fail "processing #{lang} KO\n" if error_code
+      print "processing #{lang} OK\n"
+      end
+  end
+
+  desc "Continuous Integration"   
+  task :check do
+    require 'maruku'
+    langs = FileList.new('??')+FileList.new('??-??')
+    if ENV['debug'] && $lang
+      langs = [$lang]
+    else
+      excluded_langs = [
+        ]
+      excluded_langs.each do |lang|
+        puts "excluding #{lang}: known to fail"
+      end
+      langs -= excluded_langs
+    end
+    errors = langs.map do |lang|
+      print "processing #{lang} "
+      error_code=test_lang(lang, $out)
+      if error_code
+        print "KO\n"
+      else
+        print "OK\n"
+      end
+      error_code
+    end
+    fail "At least one language conversion failed" if errors.any?
+  end
+
+end

data/test/progit/ar/01-introduction/01-chapter1.markdown

@@ -0,0 +1,264 @@
+# الإستعداد للبدء! #
+
+يحتوي هذا الفصل على معلومات تعدك للبدء بإستخدام Git. سنبدأ بشرح بعض المعلومات الأساسية عن نظم إدارة الإصدارات (Version Control System)، ثم سننتقل إلى كيفية تنصيب وتشغيل Git على نظامك ومن ثم كيف يمكنك استخدامها في عملك. في نهاية الفصل ستكون قد تعرفت على أهمية وجود Git، لماذا عليك إستخدامها وكيف تستعد لذلك.
+
+## إدارة الإصدارات (Version Control) ##
+
+ما هو نظام إدارة الإصدارات، ولماذا عليك أن تهتم به؟ تمكنك هذه الأنظمة من تسحيل التغيرات التي تحدث على ملف أو مجموعة ملفات خلال الزمن بحيث يمكنك الرجوع الى مرحلة معينة (إصدار) لاحقاً. فعلى سبيل المثال، ستستخدم في هذا الكتاب الكود المصدري للملفات في حين أنه تتم إدارتها من قبل نظام إدارة الإصدارات، ولكن في الحقيقة يمكنك استخدام هذه الأنظمة مع أي نوع من الملفات على حاسوبك.
+
+إذا كنت تعمل كمصمم غرافيك أو ويب وتريد طريقة لمتابعة جميع الإصدارت والتعديلات التي تجريها على صورة أو قالب ما (الأمر الذي سيعجبك بالتأكيد)، فإن نظام إدارة الإصدارات (VCS) هو الحل الأمثل. حيث يمكنك من إرجاع الملفات الى حالة كانت عليها سابقاً، أو ارجاع المشروع بأكمله لحالة سابقة، يمكنك أيضاً مقارنة التغيرات الحاصلة مع مرور الزمن، أو معرفة من قام بتعديل معين أدى الى خطأ ما، من قام بتقديم إقتراح ومتى قام بذلك، والمزيد. إستخدامك لنظام إدارة الإصدارات يعني أيضاً أنه اذا قمت بخطأ ما في مرحلة من المراحل أو خسرت ملفات المشروع لسبب ما، يمكنك استرجاعها الى حالها بسهولة. كل هذه الميزات مقابل تعب خفيف منك.
+
+### أنظمة إدارة الإصدارات المحلية ###
+
+تقوم الطريقة التي يقوم بها معظم المستخدمين لإدارة إصداراة مشاريعهم على "نسخ الملفات" الى مكان آخر. يقوم المعظم بهذه الطريقة لأنها تبدوا وكأنها الحل الأسهل، ولكنها تجلب المشاكل والأخطاء بشكل لا يحتمل أيضاً. من السهل جداً أن تنسى بأي مجلد وضعت نسخة معينة أو أن تقوم بالتغيير أو الحذف عن طريق الخطا لملف ما.
+
+لعلاج هذه المشكلة، قام المبرمجون بتطوير أنظمة إدارة إصدارات المحلية، حيث تستخدم قاعدة بيانات بسيطة تحفظ فيها التغيرات على الملفات في نظام إصدارات معين (إنظر الشكل 1-1).
+
+
+Insert 18333fig0101.png 
+الشكل 1-1. مخطط أنظمة إدارة الإصدارات المحلية.
+
+أحد أشهر أنظمة إدارة الإصدارات هو نظام يدعى rcs، والذي مازال يتم توزيعه مع العديد من الحواسيب في يومنا هذا. حتى أن أنظمة Mac OS X الشهيرة تحوي نظام rcs مضمنة في حزمة برامج التطوير Developer Tools. يقوم عمل هذه الأداة ببساطة على حفظ مجموعات من الإصلاحات (Patch sets) (أي فروقات بين الملفات بمعنى آخر) من تغيير الى آخر بطريقة خاصة; يمكنها بعد ذلك اعادة تشكيل أي ملف بالطريقة التي كان عليها في أي مرحلة خلال حياة الملف عن طريق اضافة جميع هذه التغيرات.
+
+### أنظمة إدارة الإصدارات المركزية ###
+
+المشكلة التالية التي ظهرت هي الرغبة في التعاون والتشارك بين المطورين الذين يعملون على أنظمة أخرى. لحل هذه المشكلة تم إنشاء أنظمة إدارة الإصدارات المركزية Centralized Version Control Systems. تقوم هذه الأنظمة، مثل CVS, Subversion و Perforce على مخدم Server واحد يحتوي على جميع الملفات، وعدد من المستخدمين Clients تقوم بطلب هذه الملفات من مكان وجودها المركزي. للعديد من السنوات، كانت هذه الأنظمة هي المسيطرة على عالم إدارة الإصدارات (انظر الشكل 1-2).
+
+Insert 18333fig0102.png 
+الشكل 1-2. مخطط أنظمة إدارة الإصدارات المركزية.
+
+تقدم هذه الطريقة العديد من الأفضليات على أنظمة ادارة الإصدارات المحلية. فعلى سبيل المثال، جميع المشاركين في المشروع يعرف مالذي يقوم به المشارك الآخر الى حد معين. مدراء المشروع يستطيعون التحكم بمن يستطيع فعل ماذا في النظام العام; وبالطبع فإنه من الأسهل التعامل مع أنظمة إدارة الإصدارات المركزية على التعامل مع الأنظمة المحلية وقاعدات بياناتها من قبل كل مستخدم.
+
+ولكن، ومن جهة ثانية، فإن لهذه الطريقة جانباً سيئاً أيضاً. أهم هذه النقاط السيئة هي أنه هذه الأنظمة المركزية تقوم على مركز واحد للكود، أي إنه اذا حصل وتوقف المخدم لساعة، فلن يتمكن أحد من خفظ التغييرات أو القيام بأي تعديل على أي شيء يعمل عليه. إذا حصل وأن تعطل القرص الأساسي والذي يحوي على قاعدة البيانات المركزية، ولم تعمل النسخ الإحتياطية المخبأة، فإنك ستخسر كل شي عن تاريخ عملك في المشروع. تعاني أنظمة إدارة الإصدارات المحلية من هذه المشكلة أيضاً، وهي أنه عندما تكون جميع ملفات المشروع في مكان واحد فإنك على خطر من خساراة كل شيء!
+
+### أنظمة إدارة الإصدارات الموزعة ###
+
+وهنا تأتي أنظمة إدارة الإصدارات الموزعة لحل المشكلة. في هذه الأنظمة (مثل Git, Mercurial, Bazaar أو Darcs) يحصل المستخدمون ليس فقط على آخر نسخة من الملفات الموجود على المخدم، بل على كامل تاريخ النظام. في هذه الحال، إن تعطل النظام، فإنه يمكن الحصول على نسخة من المشروع من أي مستخدم الى المخدم مرة أخرى. أي أن كل عملية طلب للكود هي في الحقيقة عملية حفظ كاملة وشاملة لتاريخ المشروع (إنظ الشكل 1-3).
+
+
+Insert 18333fig0103.png 
+الشكل 1-3. مخطط أنظمة إدارة الإصدارات الموزعة.
+
+وفوق هذا فإن معظم هذه الأنظمة يتعامل بشكل جيد جداً مع أكثر من نسخة خارجية للمشروع، أي يمكنك التعاون مع أكثر من مجموعة مختلفة من الأشخاص في طرق مختلفة وفي وقت واحد وعلى مشروع واحد. يمكنك هذا من تطوير أكثر من طريقة عمل واحدة مناسبة لك، الأمر الذي لم يكن متاحاً مع أنظمة إدارة الإصدارات المركزية.
+
+## لمحة تاريخية عن Git ##
+
+كما تبدأ العديد من الأشياء الجميلة في الحياة، بدأت Git كنوع من التدمير المبدع المثير للجدل. الـ Linux Kernel المعروف هو برنامج مفتوح المصدر ذو إطار واسع نوعاً ما. طوال حياة هذا المشروع (من 1991-2002)، كان يتم تناقل التعديلات على شكل ملفات إصلاح و ملفات مؤرشفة (مضغوطة). في 2002، في 2002 بدأ المشروع باستخدام نظام إدارة إصارات موزعة DVCS يدعى BitKeeper.
+
+في 2005، بدأت العلاقة بالإنهيار بين المجتمع المطور للـ Linux Kernel والمجتمع التجاري المطور لـ BitKeeper، وتم العدول عن توفير البرنامج بشكل مجاني. أثار هذا التغيير الرغبة في المجتمع المطور لـ Linux (وبالتحديد لينوس تورفالدوس، منشيء Linux) الى تطوير نظامهم الخاص بناء على الدروس التي تعلموها عند استخدامهم لـ BitKeeper. وتم وضع أهداف لكي يحققها النظام الجديد مشمولة بـ:
+
+*	السرعة
+*	التصميم البسيط
+*	الدعم القوي للبرمجة الغير خطية (الكثير من أشجار التطوير الفرعي)
+*	التوزيع بشكل كامل
+*	القدرة على تحمل مشروعات ضخمة مثل الـ Linux Kernel بشكل فعال (السرعة وحجم المعلومات)
+
+منذ ولادة Git في 2005، تطورت لكي تصبح ناضجة مع المحافظة على السهولة والمبادئ الأساسية التي وضعت عليها. حيث أنها سريعة بشكل لايصدق، و فعالة مع المشاريع الكبيرة، وتحوي على نظام تشجير ممتاز لدعم التطوير الغير خطي (انظر الفصل 3).
+
+## أوليات Git ##
+
+لنتحدث الآن عن Git بشكل سريع. هذا القسم هام جداً لك، لأنك إذا عرفت ماهي Git وماهيا أوليات عملها، سيكون من السهل عليك استخدام Git بشكل أسهل وأفضل. وخلال تعلمك لـ Git حاول أن تفرغ ذهنك من المعلومات السابقة عن أنظمة إدارة الإصدارات الأخرى، مثل Subversion أو Perforce; سيجنبك هذا من الخلط بين المعلومات عند استخدام هذه الأداة. تقوم Git بالتعامل وتخزين المعلومات بشكل مختلف تماماً عن الأنظمة الأخرى، وبالرغم من أن واجهة الإستخدام بسيطة نسبياً; سيكون فهمك لهذه الإختلافات سيبعد عنك الحيرة عند الإستخدام.
+
+### لفطات، وليست تغيرات ###
+
+الفرق الرئيسي بين Git وأي نظام إدارة إصدارات آخر (Subversion وأصدقاءه) هو الطريقة التي تتعامل بها Git مع المعلومات. تقوم معظم هذه الأنظمة بتخزين المعلومات كقائمة من التغيرات القائمة على الملفات. هذه الأنظمة (مثل CVS، Subversion، Perforce، Bazaar وغيرها) تتعامل مع المعلومات التي تحفظها كمجموعة ملفات والتغيرات القائمة عليها مع مرور الوقت، كما هو موضح في الشكل 1-4.
+
+Insert 18333fig0104.png 
+الشكل 1-4. الأنظمة الاخرى تقوم بحفظ معلومات التغيرات الحاصلة على كل ملف وكأنها الإصدار الأول.
+
+الأمر مختلف مع Git. حيث تعامل Git المعلومات المخزنة على أنها "لقطات" من نظام ملفات مصغر. ففي كل مرة تقوم بـ Commit أو تحفظ حالة المشروع، تقوم Git بأخذ صورة عن جميع الملفات في تلك اللحظة وتخزن رابطاً الى تلك اللقطة. ومن أجل السرعة، إذا لم يتغير الملف، لا تقوم Git بحفظة، بل تحفظ رابطاً عن الملف الأسبق منه المطابق. تتعامل Git مع المعلومات كما هو موضح في الشكل 1-5.
+
+Insert 18333fig0105.png 
+الشكل 1-5. تحفظ Git المعلومات على أنها "لفطات".
+
+وبالطبع، هذا الإختلاف بين Git وبين جميع أنظمة إدارة الإصدارات الأخرى تقريباً. يجعل هذا Git أشبه بنظام ملفات مصغر مزود بأدوات خارقة مبنية عليه، عوضاً عن نظام إدارة إصدارات عادي. سنقوم بشرح الفوائد التي تحصل عليها عندما تتعامل مع المعلومات بهذه الطريقة في الفصل الثالث "التشعيب في Git".
+
+### جميع العمليات هي عمليات داخلية تقريباً ###
+
+أغلب العمليات في Git لا تحتاج سوى ملفات ومصادر داخلية لتعمل - أي بشكل عام، لا توجد معلومات تحتاجها من حاسوب آخر من الشبكة. إذا كنت قد استخدمت أحد أنظمة إداراة الإصدارات الأخرى والتي تعتمد عملياتها بشكل كبير على الشبكة فإن هذا سيجعلك تعتقد أن آلهة السرعة قد باركت Git وأعطتها هذه السرعة الجبارة. ستجد أنك تملك كامل تاريخ مشروعك موجود أمامك مباشرة، وأغلب العمليات أقرب ما تكون الى الآنية.
+
+فعلى سبيل المثال، لكي تستعرض تاريخ مشروعك، لن تحتاج Git الى الذهاب الى مخدم معين للحصول عليه وعرضه، بل تقوم بقراءته مباشرة من حاسوبك. اي انك ستحصل على تاريخ مشروعك بشكل مباشر. اذا أردت استعراض التغيرات الحاصلة بين الإصدار الحالي لملف ما واصدار الشهر السابق، تستطيع Git النظر الى الملف من الشهر السابق وحساب الفروقات بينهما مباشرة، عوضاً عن طلب هذه المعلومات من مخدم خارجي.
+
+هذا يعني أيضاً أن الأمور التي لا تستطيع فعلها عندما تكون مفصولاً عن الإنترنت أو عن الشبكة الداخلية قليلة جداً. إذا كنت في طائرة أو في القطار ولم تستطيع الإرتباط بالشبكة بشكل صحيح، يمكنك إكمال عملك بشكل طبيعي. في الأنظمة الأخرى يكون هذا الأمر مستحيلاً! أو من الممكن لك أن تعدل الملفات ولكن دون عمليات Commit لتغييراتك. في نظام Perforce على سبيل المثال، لا يمكنك فعل الكثير حينما تكون مفصولاً عن المخدم الأساسي; وفي Subversion أو CVS، يمكنك التعديل على الملفات لكن بدون عمليات Commit لتعديلاتك، قد تعتقد بأن هذا ليس بالأمر الكبير، ولكن ستتفاجئ بحجم الفرق الذي يصنعه.
+
+### Git تحمل المصداقية ###
+
+كل شيء في Git سيتم وضع Check-sum عليه قبل تخزينة حيث ستتم الإشارة اليه لاحقاً بهذه الـ checksum. هذا يعني أنه من المستحيل أن يتم تغيير أي ملف أو مجلد دون أن يتم اعلام Git بهذا التغيير. تم بناء هذه الخاصية بشكل أساسي في فلسفة وطريقة عمل Git. من المستحيل أن تخسر معلوماتك بشكل فجائي أو أن ينعطب معلف ما دون أن تعرف Git بذلك.
+
+تدعى الآلية التي تستخدمها Git لعملية الـ checksum هذه باسم SHA-1 hash. وهي عبارة عن قيمة نصية من 40 محرف ستاعشري (0-9 و a-f) ويتم حسابها بناء على محتوى الملف أو المجلد الذي تتبعه Git. يبدو الـ hash من نوع SHA-1 كما يلي:
+
+	24b9da6552252987aa493b52f8696cd6d3b00373
+
+سترى أن هذه القيم ستكون موجودة في كل مكان في Git ذلك لأنها تستخدمها بشكل كثيف. في الحقيقة، تستخدم Git هذه القيم للدلالة على الملفات في قاعدة بياناتها.
+
+### Git تضيف المعلومات فقط! ###
+
+عندما تقوم بعملياتك في Git، ستقوم Git في أغلب الأحيان بإضافة معلومات فقط الى قاعدة البيانات. ومن الصعب جداً القيام بعملية بحيث لا يمكنك العودة الى الوراء فيها أو محيها من قاعدة البيانات بشكل نهائي. ولكن، وكما هو الأمر في أغلب نظم إدارة الإصدارات، من الممكن أن تخسر المعلومات قبل القيام بعملية Commit للتغيرات الحاصلة; ولكن بعد عملية الـ commit في Git، من الصعب جداً خسارة المعلومات، وخاصة اذا كنت تقوم بعملية push للتعديلات من قاعدة بياناتك الى repository اخرى بشكل منظم.
+
+سيضيف هذا الكثير من المتعة لإستخدامك لـ Git، لأننا نعرف أنه بإمكاننا القيام بالتجارب دون خطر تعريض المعلومات للخطر أو الضياع. للحصول على معلومات معمقة أكثر عن كيفية حفظ Git للمعلومات وكيفية استرجاعها انظر فقرة "Under the Cover" في الفصل التاسع.
+
+### الحالات الثلاثة ###
+
+والآن عليك الإنتباه قليلاً.  الأمر الأساسي الذي عليك أن تتذكره في Git اذا أردت أن تكمك تعلمك بسلاسة هو أنه في Git توجد ثلاث حالات أساسية يمكن للملفاتك أن تكون عليها: commited، معدلة أو مهيئة للعملية commit (أو staged). نعني بـ commitedf بأن المعلومات تم تخزينها بآمان في قاعدة بياناتك الخاصة. "معدل" تعني أنك قمت ببعض التعديلات على الملف ولكنك لم تقبل بعملية Commit عليه بعد. أما "مهيأ (Staged)" فتعني بأنك حددت ملفاً قمت بتعديله بإصداره الحالية ليتم حفظ في عملية الـ commit التي ستقوم بها.
+
+يقودنا هذا الى الحديث عن الأقسام الثلاثة الرئيسية في أي مشروع Git: المجلد الخاص بـ Git، مجلد العمل و مكان التهييئ (staging area).
+
+Insert 18333fig0106.png 
+الشكل 1-6. المجلد الخاص بـ Git، مجلد العمل و مكان التهييئ (staging area).
+
+المجلد الخاص بـ Git هو المكان الذي تحفظ فيه Git المعلومات الخاصة بها عن مشروعك. هذا هو المكان الأكثر أهمية في Git، وهو الذي يتم نسخه عندما تنسخ الـ repository من حاسوب آخر.
+
+مجلد العمل هو النسخة الحالية المسحوبة من مشروعك. الملفات التي سيتم سحبها من قاعدة بيانات Git للمشروع وتجهيزها لك لتقوم بتعديلها.
+
+مكان التهييئ (staging area)، عادة ما تكون موجودة في مجلد Git لمشروعك، وتحتوي على المعلومات التي سيتم عملية commit عليها. قد يشار الى هذا المكان أيضاً باسم الفهرس (index).
+
+خطوات العمل الإعتيادية في Git غالباً ما تكون كالتالي:
+
+1. تقوم بالتعديلات على الملفات في مجلد العمل.
+2. تقوم بوضع هذه الملفات في مكان التهييئ (staging area)، حيث تقوم بإضافة اللقطات الى الـ staging area.
+3. تقوم بعملية Commit، يتم أخذ الملفات المهيئة من مكان التهيئة Staging Area وتقوم بتخزين هذه الللقطة بشكل نهائي في مجلد عمل Git.
+
+إذا كان هناك إصدار معين لملف، فسيكون Commited. إذا كان معدل ومضاف إلى مكان التهييئ staging area فهو مهيئ staged. 
+If a particular version of a file is in the git directory, it’s considered committed. If it’s modified but has been added to the staging area, it is staged. And if it was changed since it was checked out but has not been staged, it is modified. In Chapter 2, you’ll learn more about these states and how you can either take advantage of them or skip the staged part entirely.
+
+## تصيب Git ##
+
+والآن لنبدأ باستخدام Git! ولكن أولاً علينا تنصيبها على نظامنا. يمكنك الحصول على Git بأكثر من طريقة. الطريقتين الأكثر شهرة هي إما أن تنصبها يدوياً من الكود المصدري أو أن تحصل على تنصيب مهيئ لنظامك مباشرة.
+
+
+### التنصيب من الكود المصدري ###
+
+بالطبع، من المفضل أن تقوم بتنصيب Git من الكود المصدري (أي أن تقوم ببناء Git يدوياً، إن استطعت) وذلك لأنك ستحصل دائماً على آخر نسخة منها. كل اصدار جديد من Git غالباً ما يحوي على تحسينات في واجهة الإستخدام. بالإضافة إلى أنك ستحصل على اصدار قديم اذا كنت تستخدم احدى توزيعات لينكس المختلفة. ولذلك، إذا لم تكن على توزيعة حديثاً جداً من المفضل أن تقوم بتنصيب مباشرة من الكود المصدري لـ Git.
+
+لتنصيب Git، عليك أن تتحق من أن نظامك يحوي على المكتبات التالية، والتي تعتمد عليها Git، وهي: curl, zlip, openssl, expat و libiconv. على سبيل المثال، اذا كنت على نظام يحوي على أداة yum (مثل فيدورا Fedora) أو apt-get (مثل ديبيان Debian)، يمكنك تشغيل أحد الأوامر التالية للتأكد من تواجد هذه المكتبات:
+
+	$ yum install curl-devel expat-devel gettext-devel \
+	  openssl-devel zlib-devel
+
+	$ apt-get install libcurl4-gnutls-dev libexpat1-dev gettext \
+	  libz-dev
+
+بعد تأكدك من المكتبات المطلوبة، يمكنك الحصول على آخر نسخة من الكود المصدري لـ Git من الموقع:
+
+	http://git-scm.com/download
+	
+ثم، يمكنك البناء والتنصيب:
+
+	$ tar -zxf git-1.6.0.5.tar.gz
+	$ cd git-1.6.0.5
+	$ make prefix=/usr/local all
+	$ sudo make prefix=/usr/local install
+
+بعد ذلك، ستتمكن من الحصول على تحديثات على الكود المصدري لـ Git من خلال Git نفسها :)
+
+	$ git clone git://git.kernel.org/pub/scm/git/git.git
+	
+### التنصيب على لينكس ###
+
+إذا أردت تنصيب Git على نظام لينكس دون بناءه يدوياً، يمكنك ذلك من خلال أداة النصيب الخاصة بنظامك والتي تأتي مع نظامك. على سبيل المثال اذا كنت تستخدم نظام فيدورا Fedora، يمكنك استخدام yum:
+
+	$ yum install git-core
+
+أو اذا كنت على نظام مبنى على ديبيان Debian مثل أوبونتو Ubuntu، يمكنك استخدام apt-get كالتالي:
+
+	$ apt-get install git
+
+### التنصيب على نظام الماك أو اس ###
+
+
+هناك طريقتين للتنصيب على  ماك أو اس، الأسهل هي استخدام الواجهة الرسومية للتنصيب، والتي يمكنك تحميلها من صفحة المشروع على غوغل كود (انظر الشكل 1-7):
+
+	http://sourceforge.net/projects/git-osx-installer/
+
+Insert 18333fig0107.png 
+الشكل 1-7. تنصيب Git على ماك أو اس.
+
+والطريقة الأكثر شهرة للحصول على Git هي من خلال MacPorts، ("http://macports.org"). يمكنك تشغيل الأمر التالي اذا كنت قد نصبت MacPorts من قبل:
+
+	$ sudo port install git-core +svn +doc +bash_completion +gitweb
+
+يمكنك عدم تنصيب أي من الأمور الإضافية مع Git، ولكنك ستحتاج الى +svn اذا كنت ستستخدم Git على repository تعتمد على نظام Subversion (انظر الفصل 8).
+
+
+### التنصيب على ويندوز ###
+
+يمكنك تنصيب Git على نظام ويندوز بسهولة. أحد أسهل الطرق هو استخدام مشروع msysGit. يمكنك تنصيب البرنامج من صفحة المشروع على غوغل كود:
+
+	http://msysgit.github.com/
+
+بعد التنصيب سيكون لدين نسختين من الأداة للـ command-line في ويندوز (بالإضافة الى أداة SSH والتي ستستفيد منها لاحقاً) والأداة بالواجهة الرسومية الإعتيادية.
+
+## إعداد Git لأول مرة ##
+
+والآن وبعد أن حصلت على Git على نظامك، سيتوجب عليك تخصيص بعض الخيارات لتناسب بيئتك. سيكون عليك القيام بهذه التعديلات مرة واحدة فقط; حتى بعد قيامك بتحديث نسختك من Git. ولكن بالطبع يمكنك تغيير هذه الإعدادات في أي وقت تريد.
+
+تأتي Git مرفقة بأداة تدعى git config والتي تمكنك تعديل الخيارات (المتغيرات) التي تتحكم بطريقة عمل Git. يتم حفظ هذه المتغيرات في أحد ثلاث أمكنة مختلفة:
+
+*	في ملف `/etc/gitconfig`: يحتوي على قيم لجميع المستخديم على نظامك لجميع الـ repositories أيضاً. اذا قمت بوضع إضافة ` --system` عند تشغيل الأمر `git config`، سيتم تعديل الخيارات على هذا الملف بالتحديد.
+
+*	في ملف `~/.gitconfig`: وهو مخصص للمستخدم الخاص بك فقط. سيتم تغيير الإعدادات في هذا الملف بالتحديد عن طريق إضافة `--global` الى أمر git config.
+
+*	ملف الخيارات الموجود في مجلد عمل Git (الموجود في `.git/config`) في أي repository تعمل عليها، حيث تكون هذه الإعدادات مخصصة لهذه الـ repository فقط. عليك أن تعلم أيضاً بأن الإعدادات الموجودة في أي ملف سيتم تفضيلها (أي استخدامها) على المعلومات الموجودة في الملف الأعم، أي الإعدادات الموجودة في ملف الإعدادات `.git/config` ستتفوق على تلك الموجودة في `/etc/gitconfig`.
+
+على نظام ويندوز، ستقوم Git بتفحص `.gitconfig` في مجلد الـ `$HOME` (عادة تكون `C:\Documents and Settings\$USER`). ستقوم Git أيضاً بتفقد ملف /etc/gitconfig، والذي يكون مبنياً على مكان وجود MSys، والذي تحدده أنت عندما تقوم بتنصيب Git على نظامك.
+
+### شخصيتك ###
+
+أول شيء عليك فعله بعد تنصيبك لـ Git هو اعداد اسمك وبريدك الالكتروني. أهمية هذا الأمر تكمن في أن كل عملية Commit في Git ستستخدم هذه المعلومات وسيتم لصقها بشكل غير قابل للتغيير في كل عملياتك:
+
+	$ git config --global user.name "John Doe"
+	$ git config --global user.email johndoe@example.com
+
+وطبعاً، اذا أردت أن تتحدد هذه المعلومات على كامل النظام، عليك اضافة '--global' الى الأمر. واذا أردت تجاوز هذا الأمر وتحديد معلومات مختلفة لمشروع معين، عليك تشغيل هذا الأمر بدون '--global' داخل مشروعك.
+
+### محرر النصوص ###
+
+والآن وبعد اعداد شخصيتك، يمكنك تعيين محرر النصوص الإفتراضي والذي ستستخدمه Git عندما تحتاج منك الى ادخال رسالة ما. افتراضياً، ستستخدم Git المحرر الإفتراضي المحدد للنظام، والذي يكون عادة Vi أو Vim.  إذا أردت استخدام محرر آخر، مثل Emacs، يمكن كتابة مايلي:
+ء
+	$ git config --global core.editor emacs
+	
+### أداة عرض الإختلافات Diff Tool ###
+
+أمر آخر قد تهتم بتعديله عن الخيار الإفتراضي هو أداة عرض الإختلافات Diff tool والتي ستستخدمها لحل التعارضات بين الإصدارات عن الدمج. فعلى سبيل المثال، لإستخدام أداة vimdiff:
+
+	$ git config --global merge.tool vimdiff
+
+تقبل Git كلا من: kdiff3، tkdiff، meld، xxdiff، emerge، vimdiff، gvimdiff، ecmerge و opendiff كأدوات فعالة، يمكنك إضافة خيارات أخرى خاصة أيضاً، انظر الفصل السابع لمعلومات اخرى عن كيفية القيام بهذا.
+
+### تغيير الإعدادات ###
+
+اذا أردت القاء نظرة على إعداداتك، يمكنك استخدام أمر 'git config --list' لعرض قائمة بكافة الخيارات التي أعددتها في Git:
+
+	$ git config --list
+	user.name=Scott Chacon
+	user.email=schacon@gmail.com
+	color.status=auto
+	color.branch=auto
+	color.interactive=auto
+	color.diff=auto
+	...
+
+من الممكن أن ترى هذه المفاتيح أكثر من مرة، ذلك لأن Git تقوم بقراءة هذه المفاتيح من الملفات المختلفة (`/etc/gitconfig` و `~/.gitconfig`, على سبيل المثال). في هذه الحاله، تقوم Git باستخدام آخر قيمة موجودة لكل مفتاح مختلف.
+
+يمكنك أيضاً تفحص القيمة التي "تتعامل" معها Git لأي مفتاح مختلف عن طريق الأمر `git config {key}`:
+
+	$ git config user.name
+	Scott Chacon
+
+## الحصول على المساعدة ##
+
+هناك أكثر من طريقة للحصول على المساعدة أثناء استخدامك لـ Git، يمكنك كتابة أحد الأوامر التالية:
+
+	$ git help <verb>
+	$ git <verb> --help
+	$ man git-<verb>
+على سبيل المثال، يمكنك الحصول على المساعدة لاستخدام أمر config عن طريق الأمر التالي:
+
+	$ git help config
+
+تكمن روعة هذه الأوامر بأنه يمكنك الوصول اليها من أي مكان، حتى ولو لم تكن موصولاً بالشبكة.
+إذا لم تكن صفحات المساعدة السابقة أو هذا الكتاب كافية بالنسبة اليك يمكنك الذهاب الى قناة #git أو #github على شبكة IRC Freenode (irc.freenode.net). عادة ما تكون هذه القنوات مليئة بالعديد من الخبراء بكيفية عمل Git ومستعدين للمساعدة.
+
+## الملخص ##
+
+لقد حصلت حتى الآن على معلومات أولية عن نظام Git وماهي اختلفاته عن أنظمة ادارة الإصدارات المركزية الآخرى. يجب أن تكون قد حصلت على نسخة من Git تعمل على نظامك. والآن حان الوقت لتعلم بعض مبادئ استخدام Git.