diff --git a/.dependabot/config.yml b/.dependabot/config.yml new file mode 100644 index 000000000..3beccd890 --- /dev/null +++ b/.dependabot/config.yml @@ -0,0 +1,14 @@ +version: 1 +update_configs: + # Update your Gemfile (& lockfiles) as soon as + # new versions are published to the RubyGems registry + - package_manager: "ruby:bundler" + directory: "/" + update_schedule: "live" + + # Apply default reviewer and label to created + # pull requests + default_reviewers: + - "ben" + default_labels: + - "dependabot" diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 000000000..c1b1a0a70 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,64 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: '' +assignees: '' + +--- + + + + + + + + + + + + +**Which version of the book is affected?** + + + +**Describe the bug:** + + +**Steps to reproduce:** + + + + + + +**Expected behavior:** + + +**Screenshots:** + + +**Additional context:** + + + +**Desktop:** + + +- Operating system: +- Browser/application: +- Browser/application version: + +**Smartphone:** + + +- Device: +- OS: +- Browser/application: +- Browser/application version: + +**E-book reader:** + + +- Device: +- Software Update: diff --git a/.gitignore b/.gitignore index e00a9543c..424a30e52 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ progit.pdfmarks progit.epub progit-kf8.epub progit.mobi +contributors.txt \ No newline at end of file diff --git a/.mailmap b/.mailmap new file mode 100644 index 000000000..d64acd787 --- /dev/null +++ b/.mailmap @@ -0,0 +1,2 @@ +Jean-Noël Avila +Scott Chacon \ No newline at end of file diff --git a/.tgitconfig b/.tgitconfig index 9a9773b33..a1a520376 100644 --- a/.tgitconfig +++ b/.tgitconfig @@ -1,6 +1,6 @@ [bugtraq] url = https://github.com/progit/progit2/issues/%BUGID% - logregex = "[Ii]ssues?:?(\\s*(,|and)?\\s*#?\\d+)+\n(\\d+)" + logregex = "(?:[Cc]lose[sd]?|[Ff]ix(?:e[sd])?|[Rr]esolve[sd]?):?\\s+(?:[Ii]ssues?\\s+#?|#)\\d+(?:(?:,|\\s+and)\\s+(?:[Ii]ssues?\\s+#?|#)\\d+)*\n(\\d+)" [tgit] icon = Pro.ico diff --git a/.travis.yml b/.travis.yml index 93fa3069e..c28bea168 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,7 +1,8 @@ language: ruby +git: + depth: false cache: bundler before_install: -- gem install bundler - bundle install after_success: - script/tag_on_master @@ -9,12 +10,14 @@ script: bundle exec rake book:build env: secure: "O+YCTDgLfCYAJjjOv2sApDRV5NJe6pkhiYIkORFuf2flO8HE72fEtDRpSWh1vulnIH6AjRK2jH7C8qA3MVbUO8D0io+Ha+vnbMXIp1JPCptcJNEkJrW13VTR66SWOzsgLp3mCrIC+YdE2JoYWGcnDsRMQwdnrWnxBzSOd22ZKzU=" +before_deploy: bundle install && bundle exec rake book:build deploy: provider: releases file: - progit.epub - progit.mobi - progit.pdf + - progit.html skip_cleanup: true on: tags: true @@ -28,4 +31,4 @@ branches: notifications: email: on_success: never - on_failure: always \ No newline at end of file + on_failure: always diff --git a/book/A-git-in-other-environments/1-git-other-environments.asc b/A-git-in-other-environments.asc similarity index 53% rename from book/A-git-in-other-environments/1-git-other-environments.asc rename to A-git-in-other-environments.asc index 911539045..19f22e4be 100644 --- a/book/A-git-in-other-environments/1-git-other-environments.asc +++ b/A-git-in-other-environments.asc @@ -1,3 +1,4 @@ +[[A-git-in-other-environments]] [appendix] == Git in Other Environments @@ -6,18 +7,23 @@ You can work with local files, connect your repository to others over a network, But the story doesn't end there; Git is usually used as part of a larger ecosystem, and the terminal isn't always the best way to work with it. Now we'll take a look at some of the other kinds of environments where Git can be useful, and how other applications (including yours) work alongside Git. -include::sections/guis.asc[] +include::book/A-git-in-other-environments/sections/guis.asc[] -include::sections/visualstudio.asc[] +include::book/A-git-in-other-environments/sections/visualstudio.asc[] -include::sections/eclipse.asc[] +include::book/A-git-in-other-environments/sections/visualstudiocode.asc[] +include::book/A-git-in-other-environments/sections/eclipse.asc[] -include::sections/bash.asc[] +include::book/A-git-in-other-environments/sections/jetbrainsides.asc[] -include::sections/zsh.asc[] +include::book/A-git-in-other-environments/sections/sublimetext.asc[] -include::sections/powershell.asc[] +include::book/A-git-in-other-environments/sections/bash.asc[] + +include::book/A-git-in-other-environments/sections/zsh.asc[] + +include::book/A-git-in-other-environments/sections/powershell.asc[] === Summary diff --git a/B-embedding-git-in-your-applications.asc b/B-embedding-git-in-your-applications.asc new file mode 100644 index 000000000..782e177de --- /dev/null +++ b/B-embedding-git-in-your-applications.asc @@ -0,0 +1,20 @@ +[[B-embedding-git-in-your-applications]] +[appendix] +== Embedding Git in your Applications + +If your application is for developers, chances are good that it could benefit from integration with source control. +Even non-developer applications, such as document editors, could potentially benefit from version-control features, and Git's model works very well for many different scenarios. + +If you need to integrate Git with your application, you have essentially two options: spawn a shell and call the `git` command-line program, or embed a Git library into your application. +Here we'll cover command-line integration and several of the most popular embeddable Git libraries. + +include::book/B-embedding-git/sections/command-line.asc[] + +include::book/B-embedding-git/sections/libgit2.asc[] + +include::book/B-embedding-git/sections/jgit.asc[] + +include::book/B-embedding-git/sections/go-git.asc[] + +include::book/B-embedding-git/sections/dulwich.asc[] + diff --git a/book/C-git-commands/1-git-commands.asc b/C-git-commands.asc similarity index 53% rename from book/C-git-commands/1-git-commands.asc rename to C-git-commands.asc index e24e546ea..f919ef2f6 100644 --- a/book/C-git-commands/1-git-commands.asc +++ b/C-git-commands.asc @@ -1,3 +1,4 @@ +[[C-git-commands]] [appendix] == Git Commands @@ -7,6 +8,13 @@ However, this leaves us with examples of usage of the commands somewhat scattere In this appendix, we'll go through all the Git commands we addressed throughout the book, grouped roughly by what they're used for. We'll talk about what each command very generally does and then point out where in the book you can find us having used it. +[TIP] +==== +You can abbreviate long options. +For example, you can type in `git commit --a`, which acts as if you typed `git commit --amend`. +This only works when the letters after `--` are unique for one option. +Do use the full option when writing scripts. +==== === Setup and Config @@ -21,24 +29,59 @@ There are several files this command will read from and write to so you can set The `git config` command has been used in nearly every chapter of the book. -In <<_first_time>> we used it to specify our name, email address and editor preference before we even got started using Git. - -In <<_git_aliases>> we showed how you could use it to create shorthand commands that expand to long option sequences so you don't have to type them every time. - -In <<_rebasing>> we used it to make `--rebase` the default when you run `git pull`. - -In <<_credential_caching>> we used it to set up a default store for your HTTP passwords. - -In <<_keyword_expansion>> we showed how to set up smudge and clean filters on content coming in and out of Git. - -Finally, basically the entirety of <<_git_config>> is dedicated to the command. +In <> we used it to specify our name, email address and editor preference before we even got started using Git. + +In <> we showed how you could use it to create shorthand commands that expand to long option sequences so you don't have to type them every time. + +In <> we used it to make `--rebase` the default when you run `git pull`. + +In <> we used it to set up a default store for your HTTP passwords. + +In <> we showed how to set up smudge and clean filters on content coming in and out of Git. + +Finally, basically the entirety of <> is dedicated to the command. + +[[_core_editor]] +==== git config core.editor commands + +Accompanying the configuration instructions in <>, many editors can be set as follows: + +.Exhaustive list of `core.editor` configuration commands +[cols="1,2",options="header"] +|============================== +|Editor | Configuration command +|Atom |`git config --global core.editor "atom --wait"` +|BBEdit (Mac, with command line tools) |`git config --global core.editor "bbedit -w"` +|Emacs |`git config --global core.editor emacs` +|Gedit (Linux) |`git config --global core.editor "gedit --wait --new-window"` +|Gvim (Windows 64-bit) |`git config --global core.editor "'C:/Program Files/Vim/vim72/gvim.exe' --nofork '%*'"` (Also see note below) +|Kate (Linux) |`git config --global core.editor "kate"` +|nano |`git config --global core.editor "nano -w"` +|Notepad (Windows 64-bit) |`git config core.editor notepad` +|Notepad++ (Windows 64-bit) |`git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"` (Also see note below) +|Scratch (Linux)|`git config --global core.editor "scratch-text-editor"` +|Sublime Text (macOS) |`git config --global core.editor "/Applications/Sublime\ Text.app/Contents/SharedSupport/bin/subl --new-window --wait"` +|Sublime Text (Windows 64-bit) |`git config --global core.editor "'C:/Program Files/Sublime Text 3/sublime_text.exe' -w"` (Also see note below) +|TextEdit (macOS)|`git config --global --add core.editor "open -W -n"` +|Textmate |`git config --global core.editor "mate -w"` +|Textpad (Windows 64-bit) |`git config --global core.editor "'C:/Program Files/TextPad 5/TextPad.exe' -m` (Also see note below) +|Vim |`git config --global core.editor "vim"` +|VS Code |`git config --global core.editor "code --wait"` +|WordPad |`git config --global core.editor '"C:\Program Files\Windows NT\Accessories\wordpad.exe"'"` +|Xi | `git config --global core.editor "xi --wait"` +|============================== + +[NOTE] +==== +If you have a 32-bit editor on a Windows 64-bit system, the program will be installed in `C:\Program Files (x86)\` rather than `C:\Program Files\` as in the table above. +==== ==== git help The `git help` command is used to show you all the documentation shipped with Git about any command. While we're giving a rough overview of most of the more popular ones in this appendix, for a full listing of all of the possible options and flags for every command, you can always run `git help `. -We introduced the `git help` command in <<_git_help>> and showed you how to use it to find more information about the `git shell` in <<_setting_up_server>>. +We introduced the `git help` command in <> and showed you how to use it to find more information about the `git shell` in <>. === Getting and Creating Projects @@ -50,13 +93,13 @@ One is to copy it from an existing repository on the network or elsewhere and th To take a directory and turn it into a new Git repository so you can start version controlling it, you can simply run `git init`. -We first introduce this in <<_getting_a_repo>>, where we show creating a brand new repository to start working with. +We first introduce this in <>, where we show creating a brand new repository to start working with. -We talk briefly about how you can change the default branch from ``master'' in <<_remote_branches>>. +We talk briefly about how you can change the default branch name from ``master'' in <>. -We use this command to create an empty bare repository for a server in <<_bare_repo>>. +We use this command to create an empty bare repository for a server in <>. -Finally, we go through some of the details of what it actually does behind the scenes in <<_plumbing_porcelain>>. +Finally, we go through some of the details of what it actually does behind the scenes in <>. ==== git clone @@ -65,13 +108,13 @@ It creates a new directory, goes into it and runs `git init` to make it an empty The `git clone` command is used in dozens of places throughout the book, but we'll just list a few interesting places. -It's basically introduced and explained in <<_git_cloning>>, where we go through a few examples. +It's basically introduced and explained in <>, where we go through a few examples. -In <<_getting_git_on_a_server>> we look at using the `--bare` option to create a copy of a Git repository with no working directory. +In <> we look at using the `--bare` option to create a copy of a Git repository with no working directory. -In <<_bundling>> we use it to unbundle a bundled Git repository. +In <> we use it to unbundle a bundled Git repository. -Finally, in <<_cloning_submodules>> we learn the `--recurse-submodules` option to make cloning a repository with submodules a little simpler. +Finally, in <> we learn the `--recurse-submodules` option to make cloning a repository with submodules a little simpler. Though it's used in many other places through the book, these are the ones that are somewhat unique or where it is used in ways that are a little different. @@ -88,13 +131,13 @@ When the `git commit` command is run, by default it only looks at this staging a This command is an incredibly important command in Git and is mentioned or used dozens of times in this book. We'll quickly cover some of the unique uses that can be found. -We first introduce and explain `git add` in detail in <<_tracking_files>>. +We first introduce and explain `git add` in detail in <>. -We mention how to use it to resolve merge conflicts in <<_basic_merge_conflicts>>. +We mention how to use it to resolve merge conflicts in <>. -We go over using it to interactively stage only specific parts of a modified file in <<_interactive_staging>>. +We go over using it to interactively stage only specific parts of a modified file in <>. -Finally, we emulate it at a low level in <<_tree_objects>>, so you can get an idea of what it's doing behind the scenes. +Finally, we emulate it at a low level in <>, so you can get an idea of what it's doing behind the scenes. ==== git status @@ -102,7 +145,7 @@ The `git status` command will show you the different states of files in your wor Which files are modified and unstaged and which are staged but not yet committed. In its normal form, it also will show you some basic hints on how to move files between these stages. -We first cover `status` in <<_checking_status>>, both in its basic and simplified forms. +We first cover `status` in <>, both in its basic and simplified forms. While we use it throughout the book, pretty much everything you can do with the `git status` command is covered there. ==== git diff @@ -110,36 +153,36 @@ While we use it throughout the book, pretty much everything you can do with the The `git diff` command is used when you want to see differences between any two trees. This could be the difference between your working environment and your staging area (`git diff` by itself), between your staging area and your last commit (`git diff --staged`), or between two commits (`git diff master branchB`). -We first look at the basic uses of `git diff` in <<_git_diff_staged>>, where we show how to see what changes are staged and which are not yet staged. +We first look at the basic uses of `git diff` in <>, where we show how to see what changes are staged and which are not yet staged. -We use it to look for possible whitespace issues before committing with the `--check` option in <<_commit_guidelines>>. +We use it to look for possible whitespace issues before committing with the `--check` option in <>. -We see how to check the differences between branches more effectively with the `git diff A...B` syntax in <<_what_is_introduced>>. +We see how to check the differences between branches more effectively with the `git diff A...B` syntax in <>. -We use it to filter out whitespace differences with `-b` and how to compare different stages of conflicted files with `--theirs`, `--ours` and `--base` in <<_advanced_merging>>. +We use it to filter out whitespace differences with `-b` and how to compare different stages of conflicted files with `--theirs`, `--ours` and `--base` in <>. -Finally, we use it to effectively compare submodule changes with `--submodule` in <<_starting_submodules>>. +Finally, we use it to effectively compare submodule changes with `--submodule` in <>. ==== git difftool The `git difftool` command simply launches an external tool to show you the difference between two trees in case you want to use something other than the built in `git diff` command. -We only briefly mention this in <<_git_diff_staged>>. +We only briefly mention this in <>. ==== git commit The `git commit` command takes all the file contents that have been staged with `git add` and records a new permanent snapshot in the database and then moves the branch pointer on the current branch up to it. -We first cover the basics of committing in <<_committing_changes>>. +We first cover the basics of committing in <>. There we also demonstrate how to use the `-a` flag to skip the `git add` step in daily workflows and how to use the `-m` flag to pass a commit message in on the command line instead of firing up an editor. -In <<_undoing>> we cover using the `--amend` option to redo the most recent commit. +In <> we cover using the `--amend` option to redo the most recent commit. -In <<_git_branches_overview>>, we go into much more detail about what `git commit` does and why it does it like that. +In <>, we go into much more detail about what `git commit` does and why it does it like that. -We looked at how to sign commits cryptographically with the `-S` flag in <<_signing_commits>>. +We looked at how to sign commits cryptographically with the `-S` flag in <>. -Finally, we take a look at what the `git commit` command does in the background and how it's actually implemented in <<_git_commit_objects>>. +Finally, we take a look at what the `git commit` command does in the background and how it's actually implemented in <>. ==== git reset @@ -147,34 +190,34 @@ The `git reset` command is primarily used to undo things, as you can possibly te It moves around the `HEAD` pointer and optionally changes the `index` or staging area and can also optionally change the working directory if you use `--hard`. This final option makes it possible for this command to lose your work if used incorrectly, so make sure you understand it before using it. -We first effectively cover the simplest use of `git reset` in <<_unstaging>>, where we use it to unstage a file we had run `git add` on. +We first effectively cover the simplest use of `git reset` in <>, where we use it to unstage a file we had run `git add` on. -We then cover it in quite some detail in <<_git_reset>>, which is entirely devoted to explaining this command. +We then cover it in quite some detail in <>, which is entirely devoted to explaining this command. -We use `git reset --hard` to abort a merge in <<_abort_merge>>, where we also use `git merge --abort`, which is a bit of a wrapper for the `git reset` command. +We use `git reset --hard` to abort a merge in <>, where we also use `git merge --abort`, which is a bit of a wrapper for the `git reset` command. ==== git rm The `git rm` command is used to remove files from the staging area and working directory for Git. It is similar to `git add` in that it stages a removal of a file for the next commit. -We cover the `git rm` command in some detail in <<_removing_files>>, including recursively removing files and only removing files from the staging area but leaving them in the working directory with `--cached`. +We cover the `git rm` command in some detail in <>, including recursively removing files and only removing files from the staging area but leaving them in the working directory with `--cached`. -The only other differing use of `git rm` in the book is in <<_removing_objects>> where we briefly use and explain the `--ignore-unmatch` when running `git filter-branch`, which simply makes it not error out when the file we are trying to remove doesn't exist. +The only other differing use of `git rm` in the book is in <> where we briefly use and explain the `--ignore-unmatch` when running `git filter-branch`, which simply makes it not error out when the file we are trying to remove doesn't exist. This can be useful for scripting purposes. ==== git mv The `git mv` command is a thin convenience command to move a file and then run `git add` on the new file and `git rm` on the old file. -We only briefly mention this command in <<_git_mv>>. +We only briefly mention this command in <>. ==== git clean The `git clean` command is used to remove unwanted files from your working directory. This could include removing temporary build artifacts or merge conflict files. -We cover many of the options and scenarios in which you might used the clean command in <<_git_clean>>. +We cover many of the options and scenarios in which you might used the clean command in <>. === Branching and Merging @@ -185,48 +228,48 @@ There are just a handful of commands that implement most of the branching and me The `git branch` command is actually something of a branch management tool. It can list the branches you have, create a new branch, delete branches and rename branches. -Most of <<_git_branching>> is dedicated to the `branch` command and it's used throughout the entire chapter. -We first introduce it in <<_create_new_branch>> and we go through most of its other features (listing and deleting) in <<_branch_management>>. +Most of <> is dedicated to the `branch` command and it's used throughout the entire chapter. +We first introduce it in <> and we go through most of its other features (listing and deleting) in <>. -In <<_tracking_branches>> we use the `git branch -u` option to set up a tracking branch. +In <> we use the `git branch -u` option to set up a tracking branch. -Finally, we go through some of what it does in the background in <<_git_refs>>. +Finally, we go through some of what it does in the background in <>. ==== git checkout The `git checkout` command is used to switch branches and check content out into your working directory. -We first encounter the command in <<_switching_branches>> along with the `git branch` command. +We first encounter the command in <> along with the `git branch` command. -We see how to use it to start tracking branches with the `--track` flag in <<_tracking_branches>>. +We see how to use it to start tracking branches with the `--track` flag in <>. -We use it to reintroduce file conflicts with `--conflict=diff3` in <<_checking_out_conflicts>>. +We use it to reintroduce file conflicts with `--conflict=diff3` in <>. -We go into closer detail on its relationship with `git reset` in <<_git_reset>>. +We go into closer detail on its relationship with `git reset` in <>. -Finally, we go into some implementation detail in <<_the_head>>. +Finally, we go into some implementation detail in <>. ==== git merge The `git merge` tool is used to merge one or more branches into the branch you have checked out. It will then advance the current branch to the result of the merge. -The `git merge` command was first introduced in <<_basic_branching>>. +The `git merge` command was first introduced in <>. Though it is used in various places in the book, there are very few variations of the `merge` command -- generally just `git merge ` with the name of the single branch you want to merge in. -We covered how to do a squashed merge (where Git merges the work but pretends like it's just a new commit without recording the history of the branch you're merging in) at the very end of <<_public_project>>. +We covered how to do a squashed merge (where Git merges the work but pretends like it's just a new commit without recording the history of the branch you're merging in) at the very end of <>. -We went over a lot about the merge process and command, including the `-Xignore-space-change` command and the `--abort` flag to abort a problem merge in <<_advanced_merging>>. +We went over a lot about the merge process and command, including the `-Xignore-space-change` command and the `--abort` flag to abort a problem merge in <>. -We learned how to verify signatures before merging if your project is using GPG signing in <<_signing_commits>>. +We learned how to verify signatures before merging if your project is using GPG signing in <>. -Finally, we learned about Subtree merging in <<_subtree_merge>>. +Finally, we learned about Subtree merging in <>. ==== git mergetool The `git mergetool` command simply launches an external merge helper in case you have issues with a merge in Git. -We mention it quickly in <<_basic_merge_conflicts>> and go into detail on how to implement your own external merge tool in <<_external_merge_tools>>. +We mention it quickly in <> and go into detail on how to implement your own external merge tool in <>. ==== git log @@ -236,37 +279,37 @@ It is also often used to show differences between two or more branches at the co This command is used in nearly every chapter of the book to demonstrate the history of a project. -We introduce the command and cover it in some depth in <<_viewing_history>>. +We introduce the command and cover it in some depth in <>. There we look at the `-p` and `--stat` option to get an idea of what was introduced in each commit and the `--pretty` and `--oneline` options to view the history more concisely, along with some simple date and author filtering options. -In <<_create_new_branch>> we use it with the `--decorate` option to easily visualize where our branch pointers are located and we also use the `--graph` option to see what divergent histories look like. +In <> we use it with the `--decorate` option to easily visualize where our branch pointers are located and we also use the `--graph` option to see what divergent histories look like. -In <<_private_team>> and <<_commit_ranges>> we cover the `branchA..branchB` syntax to use the `git log` command to see what commits are unique to a branch relative to another branch. -In <<_commit_ranges>> we go through this fairly extensively. +In <> and <> we cover the `branchA..branchB` syntax to use the `git log` command to see what commits are unique to a branch relative to another branch. +In <> we go through this fairly extensively. -In <<_merge_log>> and <<_triple_dot>> we cover using the `branchA...branchB` format and the `--left-right` syntax to see what is in one branch or the other but not in both. -In <<_merge_log>> we also look at how to use the `--merge` option to help with merge conflict debugging as well as using the `--cc` option to look at merge commit conflicts in your history. +In <> and <> we cover using the `branchA...branchB` format and the `--left-right` syntax to see what is in one branch or the other but not in both. +In <> we also look at how to use the `--merge` option to help with merge conflict debugging as well as using the `--cc` option to look at merge commit conflicts in your history. -In <<_git_reflog>> we use the `-g` option to view the Git reflog through this tool instead of doing branch traversal. +In <> we use the `-g` option to view the Git reflog through this tool instead of doing branch traversal. -In <<_searching>> we look at using the `-S` and `-L` options to do fairly sophisticated searches for something that happened historically in the code such as seeing the history of a function. +In <> we look at using the `-S` and `-L` options to do fairly sophisticated searches for something that happened historically in the code such as seeing the history of a function. -In <<_signing_commits>> we see how to use `--show-signature` to add a validation string to each commit in the `git log` output based on if it was validly signed or not. +In <> we see how to use `--show-signature` to add a validation string to each commit in the `git log` output based on if it was validly signed or not. ==== git stash The `git stash` command is used to temporarily store uncommitted work in order to clean out your working directory without having to commit unfinished work on a branch. -This is basically entirely covered in <<_git_stashing>>. +This is basically entirely covered in <>. ==== git tag The `git tag` command is used to give a permanent bookmark to a specific point in the code history. Generally this is used for things like releases. -This command is introduced and covered in detail in <<_git_tagging>> and we use it in practice in <<_tagging_releases>>. +This command is introduced and covered in detail in <> and we use it in practice in <>. -We also cover how to create a GPG signed tag with the `-s` flag and verify one with the `-v` flag in <<_signing>>. +We also cover how to create a GPG signed tag with the `-s` flag and verify one with the `-v` flag in <>. === Sharing and Updating Projects @@ -278,45 +321,45 @@ When you are ready to share your work or pull changes from elsewhere, there are The `git fetch` command communicates with a remote repository and fetches down all the information that is in that repository that is not in your current one and stores it in your local database. -We first look at this command in <<_fetching_and_pulling>> and we continue to see examples of it use in <<_remote_branches>>. +We first look at this command in <> and we continue to see examples of its use in <>. -We also use it in several of the examples in <<_contributing_project>>. +We also use it in several of the examples in <>. -We use it to fetch a single specific reference that is outside of the default space in <<_pr_refs>> and we see how to fetch from a bundle in <<_bundling>>. +We use it to fetch a single specific reference that is outside of the default space in <> and we see how to fetch from a bundle in <>. -We set up highly custom refspecs in order to make `git fetch` do something a little different than the default in <<_refspec>>. +We set up highly custom refspecs in order to make `git fetch` do something a little different than the default in <>. ==== git pull The `git pull` command is basically a combination of the `git fetch` and `git merge` commands, where Git will fetch from the remote you specify and then immediately try to merge it into the branch you're on. -We introduce it quickly in <<_fetching_and_pulling>> and show how to see what it will merge if you run it in <<_inspecting_remote>>. +We introduce it quickly in <> and show how to see what it will merge if you run it in <>. -We also see how to use it to help with rebasing difficulties in <<_rebase_rebase>>. +We also see how to use it to help with rebasing difficulties in <>. -We show how to use it with a URL to pull in changes in a one-off fashion in <<_checking_out_remotes>>. +We show how to use it with a URL to pull in changes in a one-off fashion in <>. -Finally, we very quickly mention that you can use the `--verify-signatures` option to it in order to verify that commits you are pulling have been GPG signed in <<_signing_commits>>. +Finally, we very quickly mention that you can use the `--verify-signatures` option to it in order to verify that commits you are pulling have been GPG signed in <>. ==== git push The `git push` command is used to communicate with another repository, calculate what your local database has that the remote one does not, and then pushes the difference into the other repository. It requires write access to the other repository and so normally is authenticated somehow. -We first look at the `git push` command in <<_pushing_remotes>>. +We first look at the `git push` command in <>. Here we cover the basics of pushing a branch to a remote repository. -In <<_pushing_branches>> we go a little deeper into pushing specific branches and in <<_tracking_branches>> we see how to set up tracking branches to automatically push to. -In <<_delete_branches>> we use the `--delete` flag to delete a branch on the server with `git push`. +In <> we go a little deeper into pushing specific branches and in <> we see how to set up tracking branches to automatically push to. +In <> we use the `--delete` flag to delete a branch on the server with `git push`. -Throughout <<_contributing_project>> we see several examples of using `git push` to share work on branches through multiple remotes. +Throughout <> we see several examples of using `git push` to share work on branches through multiple remotes. -We see how to use it to share tags that you have made with the `--tags` option in <<_sharing_tags>>. +We see how to use it to share tags that you have made with the `--tags` option in <>. -In <<_publishing_submodules>> we use the `--recurse-submodules` option to check that all of our submodules work has been published before pushing the superproject, which can be really helpful when using submodules. +In <> we use the `--recurse-submodules` option to check that all of our submodules work has been published before pushing the superproject, which can be really helpful when using submodules. -In <<_other_client_hooks>> we talk briefly about the `pre-push` hook, which is a script we can setup to run before a push completes to verify that it should be allowed to push. +In <> we talk briefly about the `pre-push` hook, which is a script we can setup to run before a push completes to verify that it should be allowed to push. -Finally, in <<_pushing_refspecs>> we look at pushing with a full refspec instead of the general shortcuts that are normally used. +Finally, in <> we look at pushing with a full refspec instead of the general shortcuts that are normally used. This can help you be very specific about what work you wish to share. ==== git remote @@ -325,7 +368,7 @@ The `git remote` command is a management tool for your record of remote reposito It allows you to save long URLs as short handles, such as ``origin'' so you don't have to type them out all the time. You can have several of these and the `git remote` command is used to add, change and delete them. -This command is covered in detail in <<_remote_repos>>, including listing, adding, removing and renaming them. +This command is covered in detail in <>, including listing, adding, removing and renaming them. It is used in nearly every subsequent chapter in the book too, but always in the standard `git remote add ` format. @@ -333,7 +376,7 @@ It is used in nearly every subsequent chapter in the book too, but always in the The `git archive` command is used to create an archive file of a specific snapshot of the project. -We use `git archive` to create a tarball of a project for sharing in <<_preparing_release>>. +We use `git archive` to create a tarball of a project for sharing in <>. ==== git submodule @@ -341,7 +384,7 @@ The `git submodule` command is used to manage external repositories within a nor This could be for libraries or other types of shared resources. The `submodule` command has several sub-commands (`add`, `update`, `sync`, etc) for managing these resources. -This command is only mentioned and entirely covered in <<_git_submodules>>. +This command is only mentioned and entirely covered in <>. === Inspection and Comparison @@ -350,25 +393,25 @@ This command is only mentioned and entirely covered in <<_git_submodules>>. The `git show` command can show a Git object in a simple and human readable way. Normally you would use this to show the information about a tag or a commit. -We first use it to show annotated tag information in <<_annotated_tags>>. +We first use it to show annotated tag information in <>. -Later we use it quite a bit in <<_revision_selection>> to show the commits that our various revision selections resolve to. +Later we use it quite a bit in <> to show the commits that our various revision selections resolve to. -One of the more interesting things we do with `git show` is in <<_manual_remerge>> to extract specific file contents of various stages during a merge conflict. +One of the more interesting things we do with `git show` is in <> to extract specific file contents of various stages during a merge conflict. ==== git shortlog The `git shortlog` command is used to summarize the output of `git log`. It will take many of the same options that the `git log` command will but instead of listing out all of the commits it will present a summary of the commits grouped by author. -We showed how to use it to create a nice changelog in <<_the_shortlog>>. +We showed how to use it to create a nice changelog in <>. ==== git describe The `git describe` command is used to take anything that resolves to a commit and produces a string that is somewhat human-readable and will not change. It's a way to get a description of a commit that is as unambiguous as a commit SHA-1 but more understandable. -We use `git describe` in <<_build_number>> and <<_preparing_release>> to get a string to name our release file after. +We use `git describe` in <> and <> to get a string to name our release file after. === Debugging @@ -380,20 +423,20 @@ This ranges from figuring out where something was introduced to figuring out who The `git bisect` tool is an incredibly helpful debugging tool used to find which specific commit was the first one to introduce a bug or problem by doing an automatic binary search. -It is fully covered in <<_binary_search>> and is only mentioned in that section. +It is fully covered in <> and is only mentioned in that section. ==== git blame The `git blame` command annotates the lines of any file with which commit was the last one to introduce a change to each line of the file and what person authored that commit. This is helpful in order to find the person to ask for more information about a specific section of your code. -It is covered in <<_file_annotation>> and is only mentioned in that section. +It is covered in <> and is only mentioned in that section. ==== git grep The `git grep` command can help you find any string or regular expression in any of the files in your source code, even older versions of your project. -It is covered in <<_git_grep>> and is only mentioned in that section. +It is covered in <> and is only mentioned in that section. === Patching @@ -405,27 +448,27 @@ These commands help you manage your branches in this manner. The `git cherry-pick` command is used to take the change introduced in a single Git commit and try to re-introduce it as a new commit on the branch you're currently on. This can be useful to only take one or two commits from a branch individually rather than merging in the branch which takes all the changes. -Cherry picking is described and demonstrated in <<_rebase_cherry_pick>>. +Cherry picking is described and demonstrated in <>. ==== git rebase The `git rebase` command is basically an automated `cherry-pick`. It determines a series of commits and then cherry-picks them one by one in the same order somewhere else. -Rebasing is covered in detail in <<_rebasing>>, including covering the collaborative issues involved with rebasing branches that are already public. +Rebasing is covered in detail in <>, including covering the collaborative issues involved with rebasing branches that are already public. -We use it in practice during an example of splitting your history into two separate repositories in <<_replace>>, using the `--onto` flag as well. +We use it in practice during an example of splitting your history into two separate repositories in <>, using the `--onto` flag as well. -We go through running into a merge conflict during rebasing in <<_rerere>>. +We go through running into a merge conflict during rebasing in <>. -We also use it in an interactive scripting mode with the `-i` option in <<_changing_multiple>>. +We also use it in an interactive scripting mode with the `-i` option in <>. ==== git revert The `git revert` command is essentially a reverse `git cherry-pick`. It creates a new commit that applies the exact opposite of the change introduced in the commit you're targeting, essentially undoing or reverting it. -We use this in <<_reverse_commit>> to undo a merge commit. +We use this in <> to undo a merge commit. === Email @@ -437,43 +480,43 @@ Git has a number of tools built into it that help make this process easier, from The `git apply` command applies a patch created with the `git diff` or even GNU diff command. It is similar to what the `patch` command might do with a few small differences. -We demonstrate using it and the circumstances in which you might do so in <<_patches_from_email>>. +We demonstrate using it and the circumstances in which you might do so in <>. ==== git am The `git am` command is used to apply patches from an email inbox, specifically one that is mbox formatted. This is useful for receiving patches over email and applying them to your project easily. -We covered usage and workflow around `git am` in <<_git_am>> including using the `--resolved`, `-i` and `-3` options. +We covered usage and workflow around `git am` in <> including using the `--resolved`, `-i` and `-3` options. -There are also a number of hooks you can use to help with the workflow around `git am` and they are all covered in <<_email_hooks>>. +There are also a number of hooks you can use to help with the workflow around `git am` and they are all covered in <>. -We also use it to apply patch formatted GitHub Pull Request changes in <<_email_notifications>>. +We also use it to apply patch formatted GitHub Pull Request changes in <>. ==== git format-patch The `git format-patch` command is used to generate a series of patches in mbox format that you can use to send to a mailing list properly formatted. -We go through an example of contributing to a project using the `git format-patch` tool in <<_project_over_email>>. +We go through an example of contributing to a project using the `git format-patch` tool in <>. ==== git imap-send The `git imap-send` command uploads a mailbox generated with `git format-patch` into an IMAP drafts folder. -We go through an example of contributing to a project by sending patches with the `git imap-send` tool in <<_project_over_email>>. +We go through an example of contributing to a project by sending patches with the `git imap-send` tool in <>. ==== git send-email The `git send-email` command is used to send patches that are generated with `git format-patch` over email. -We go through an example of contributing to a project by sending patches with the `git send-email` tool in <<_project_over_email>>. +We go through an example of contributing to a project by sending patches with the `git send-email` tool in <>. ==== git request-pull The `git request-pull` command is simply used to generate an example message body to email to someone. If you have a branch on a public server and want to let someone know how to integrate those changes without sending the patches over email, you can run this command and send the output to the person you want to pull the changes in. -We demonstrate how to use `git request-pull` to generate a pull message in <<_public_project>>. +We demonstrate how to use `git request-pull` to generate a pull message in <>. === External Systems @@ -484,13 +527,13 @@ Git comes with a few commands to integrate with other version control systems. The `git svn` command is used to communicate with the Subversion version control system as a client. This means you can use Git to checkout from and commit to a Subversion server. -This command is covered in depth in <<_git_svn>>. +This command is covered in depth in <>. ==== git fast-import For other version control systems or importing from nearly any format, you can use `git fast-import` to quickly map the other format to something Git can easily record. -This command is covered in depth in <<_custom_importer>>. +This command is covered in depth in <>. === Administration @@ -501,40 +544,40 @@ If you're administering a Git repository or need to fix something in a big way, The `git gc` command runs ``garbage collection'' on your repository, removing unnecessary files in your database and packing up the remaining files into a more efficient format. This command normally runs in the background for you, though you can manually run it if you wish. -We go over some examples of this in <<_git_gc>>. +We go over some examples of this in <>. ==== git fsck The `git fsck` command is used to check the internal database for problems or inconsistencies. -We only quickly use this once in <<_data_recovery>> to search for dangling objects. +We only quickly use this once in <> to search for dangling objects. ==== git reflog The `git reflog` command goes through a log of where all the heads of your branches have been as you work to find commits you may have lost through rewriting histories. -We cover this command mainly in <<_git_reflog>>, where we show normal usage to and how to use `git log -g` to view the same information with `git log` output. +We cover this command mainly in <>, where we show normal usage to and how to use `git log -g` to view the same information with `git log` output. -We also go through a practical example of recovering such a lost branch in <<_data_recovery>>. +We also go through a practical example of recovering such a lost branch in <>. ==== git filter-branch The `git filter-branch` command is used to rewrite loads of commits according to certain patterns, like removing a file everywhere or filtering the entire repository down to a single subdirectory for extracting a project. -In <<_removing_file_every_commit>> we explain the command and explore several different options such as `--commit-filter`, `--subdirectory-filter` and `--tree-filter`. +In <> we explain the command and explore several different options such as `--commit-filter`, `--subdirectory-filter` and `--tree-filter`. -In <<_git_p4>> and <<_git_tfs>> we use it to fix up imported external repositories. +In <> and <> we use it to fix up imported external repositories. === Plumbing Commands There were also quite a number of lower level plumbing commands that we encountered in the book. -The first one we encounter is `ls-remote` in <<_pr_refs>> which we use to look at the raw references on the server. +The first one we encounter is `ls-remote` in <> which we use to look at the raw references on the server. -We use `ls-files` in <<_manual_remerge>>, <<_rerere>> and <<_the_index>> to take a more raw look at what your staging area looks like. +We use `ls-files` in <>, <> and <> to take a more raw look at what your staging area looks like. -We also mention `rev-parse` in <<_branch_references>> to take just about any string and turn it into an object SHA-1. +We also mention `rev-parse` in <> to take just about any string and turn it into an object SHA-1. -However, most of the low level plumbing commands we cover are in <<_git_internals>>, which is more or less what the chapter is focused on. +However, most of the low level plumbing commands we cover are in <>, which is more or less what the chapter is focused on. We tried to avoid use of them throughout most of the rest of the book. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b8ffe371..8c490b141 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,94 +1,68 @@ -# Contributing to Pro Git (2nd Edition) +# همکاری در پروگیت (ویرایش دوم) -## Licensing + +## لایسنس + +ترجمه از متن انگلیسی زیر: (متن انگلیسی زیر مرجع قانون است و ترجمه تلاش بر این دارد تا به +درک آن کمک کند) By opening a pull request to this repository, you agree to provide your work under the [project license](LICENSE.asc). Also, you agree to grant such license of your work as is required for the purposes of future print editions to @ben and @schacon. Should your changes appear in a printed edition, you'll be included in the [contributors list](book/contributors.asc). -## Signaling an Issue - -Before signaling an issue, please check that there isn't already a similar one in the bug tracking system. - -Also, if this issue has been spotted on the git-scm.com site, please cross-check that it is still present in the pdf version. -The issue may have already been corrected, but the changes have not been deployed yet. - -## Small Corrections - -Errata and basic clarifications will be accepted if we agree that they improve the content. -You can also open an issue so we can figure out how or if it needs to be addressed. - -If you've never done this before, the [flow guide](https://guides.github.com/introduction/flow/) might be useful. - -## Large Rewrites - -Open an issue for discussion before you start. -These changes tend to be very subjective, often only clarifying things for some small percentage of people and it's rarely worth the time to accept them. -Professional copy editors have already reviewed this content multiple times so while you may have somewhat better taste and grammar than we do it's unlikely that your prose is going to be *so* much better that it's worth changing vast swaths of text. +با باز کردن یک درخواست پول به این مخزن، شما موافقت می‌کنید که کارتان را تحت +[لایسنس پروژه](LICENSE.asc) به اشتراک بگذارید. +همچنین موافقت می‌کنید که چنین مجوزی از کارتان بدهید چرا که برای اهداف چاپ ویرایش‌های +آینده برای @ben و @schancon ضروری است. +اگر تغییرات شما در نسخه چاپی اعمال شوند، شما در [لیست +همکاران](book/contributors.asc) خواهید بود. -## Figures +## ارجاع یک مشکل -The images in this book were generated using [Sketch 3](http://bohemiancoding.com/sketch/), with the [included sketchbook file](diagram-source/progit.sketch). +قبل از ارجاع یک مشکل، لطفاً بررسی کنید که پیشتر مشکل مشابهی در سیستم رهگیری باگ وجود نداشته باشد. -To add a figure: +همچنین اگر این مشکل سابقاً روی سایت رسمی گیت مشاهده شده، لطفاً بازنگری کنید که آیا هنوز در این مخزن موجود است یا خیر. +ممکن است پیش از این مشکل اصلاح شده باشد، اما تغییرات هنوز اعمال نشده باشند. -1. Add a page to the sketchbook. -Try to use the included symbols wherever possible. -2. Add a "slice" to your page. -Give it a name that matches the destination PNG filename, relative from the root of the source directory. -3. Make sure your slice is set to export at "800w". +## اصلاحات کوچک +اشتباهات تایپی و واضح‌سازی‌های پایه در صورتی مورد موافقت ما قرار می‌گیرند که به +صراحت محتوا را بهبود بخشند. +شما همچنین می‌توانید یک ایشو باز کنید تا ما بررسی کنیم که آیا احتیاج است و اگر +هست چگونه آنرا حل کنیم. -## Translations +اگر پیش از این هرگز چنین کاری نکرده‌اید [راهنمای +روندکاری](https://guides.github.com/introduction/flow/) ممکن است برای شما سودمند +باشد. -Translations to other languages are highly encouraged but handled a little differently than the first edition. -We now keep each translation in a separate repository. +## بازنویسی‌های بزرگ -Since each translation is a different repository, we can also have different maintainers for each project. -The Pro Git team simply pulls them in and builds them for the translation teams on the git-scm.com website. +پیش از آنکه شروع کنید برای مبحث مورد نظر یک ایشو باز کنید. +این تغییرات احتمالاً وابسته به طرز فکر اشخاص هستند و معمولاً فقط برای درصد کمی از +افراد شفاف‌سازی می‌کنند و به ندرت ارزش زحمت و زمان قبول کردن را دارند. +ویرایستارهای حرفه‌ای پیش از این، این مطالب را بارها بررسی کرده‌اند؛ بنابراین حتی +اگر شما از ادبیات یا نوشتار کم‌وبیش بهتری برخوردارید احتمال اینکه متن شما آنقدر +خوب باشد که ارزش ویرایش متقابل دریایی از متون مرتبط به خود (مثلاً در آن فصل) را +داشته باشد بسیار کم است. -### Existing Projects -If you wish to help at translating Progit 2nd edition to your -language, first check already existing projects and get in touch with -the people in charge of them if there's already one. +## اشکال -Existing projects include: +تصاویر این کتاب بوسیلهٔ [اسکچ ۳](https://www.sketchapp.com/) و با [فایل +اسکچ‌بوک نظیر](diagram-source/progit.sketch) ساخته شده‌اند. - Language | Project ------------- | ------------- -Беларуская | [progit/progit2-be](https://github.com/progit/progit2-be) -Čeština | [progit-cs/progit2-cs](https://github.com/progit-cs/progit2-cs) -English | [progit/progit2](https://github.com/progit/progit2) -Español | [progit/progit2-es](https://github.com/progit/progit2-es) -Français | [progit/progit2-fr](https://github.com/progit/progit2-fr) -Ελληνικά | [progit2-gr/progit2](https://github.com/progit2-gr/progit2) -Indonesian | [progit/progit2-id](https://github.com/progit/progit2-id) -Italiano | [progit/progit2-it](https://github.com/progit/progit2-it) -日本語 | [progit/progit2-ja](https://github.com/progit/progit2-ja) -한국어 | [progit/progit2-ko](https://github.com/progit/progit2-ko) -Nederlands | [progit/progit2-nl](https://github.com/progit/progit2-nl) -Português (Brasil) | [progit2-pt-br/progit2](https://github.com/progit2-pt-br/progit2) -Русский | [progit/progit2-ru](https://github.com/progit/progit2-ru) -Slovenščina | [progit/progit2-sl](https://github.com/progit/progit2-sl) -Српски | [progit/progit2-sr](https://github.com/progit/progit2-sr) -Türkçe | [progit/progit2-tr](https://github.com/progit/progit2-tr) -Українська| [progit/progit2-uk](https://github.com/progit/progit2-uk) -Ўзбекча | [progit/progit2-uz](https://github.com/progit/progit2-uz) -简体中文 | [progit/progit2-zh](https://github.com/progit/progit2-zh) -正體中文 | [progit/progit2-zh-tw](https://github.com/progit/progit2-zh-tw) +برای افزودن یک شکل: -### Your Language does not Exist +1. یک صفحه به اسکچ‌بوک اضافه کنید. +سعی کنید که هرجا که ممکن است از سمبل‌های از پیش اضافه شده استفاده کنید. +2. یک «اسلایس» به صفحه خود اضافه کنید. +به آن یک نام بدهید که به نام فایل پی‌ان‌جی مقصد و آدرس نسبی که از روت سورس دایرکتوری +دارد بخورد. +3. اطمینان حاصل کنید که اسلایس شما برای خروجی گرفتن به صورت روبرو تنظیم شده +باشد: 800w -Then you're lucky! You're gonna be the initiator of a new translation project! -You can start to make your own version with the second edition in English, available here. To do so, +## ترجمه‌ها - 1. Pick your the [ISO 639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) and create a GitHub organization, say `progit2-[your code]` on github - 2. Create a project progit2 - 3. Copy the structure of progit/progit2 (this project) in your project and start translating. You can reuse some material from the first edition, but beware that: - 1. the text has been reworked in numerous parts - 2. the markup has changed from markdown to [asciidoc](http://asciidoc.org) - 4. Push to the new repo a few translated chapters - 5. Ping an organizer so that the second edition of Progit in your language is pushed on git-scm.com. +اگر می‌خواهید در ترجمه پروگیت به زبان خودتان کمک کنید نگاهی به [فایل راهنمای ترجمه](TRANSLATING.md) بیاندازید. diff --git a/LICENSE.asc b/LICENSE.asc index 81f2824e2..afe0b3e99 100644 --- a/LICENSE.asc +++ b/LICENSE.asc @@ -1 +1,2 @@ -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. +این اثر تحت لایسنس Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported لایسنس شده است. +برای مشاهده یک کپی از این لایسنس به https://creativecommons.org/licenses/by-nc-sa/3.0 مراجعه کنید یا به Creative Commons در PO Box 1866، Mountain View، CA 94042، USA نامه بزنید. diff --git a/README.asc b/README.asc index 0d4498ba8..aaa88274f 100644 --- a/README.asc +++ b/README.asc @@ -1,23 +1,21 @@ -:direction: rtl - = پروگیت، ویرایش دوم -به ویرایش دوم کتاب پروگیت خوش آمدید +به ویرایش دوم کتاب پروگیت خوش آمدید. -نسخه آنلاین این کتاب را اینجا ببینید. http://git-scm.com/book/fa/v2 +نسخه آنلاین این کتاب را اینجا ببینید. http://git-scm.com/book/fa/v2 -Like the first edition, the second edition of Pro Git is open source under a Creative Commons license. +همانند ویرایش اول، ویرایش دوم پروگیت هم متن-باز تحت لایسنس «کریتیو کامنز» است. (Creative Commons) -A couple of things have changed since open sourcing the first edition. -For one, we've moved from Markdown to the amazing Asciidoc format for the text of the book. +از زمان متن-باز شدن نسخه اول تغییراتی اعمال شده. +ابتدا اینکه برای متن کتاب، ما از مارک‌دان به قالب شگفت‌انگیز اسکی‌داک مهاجرت کرده‌ایم. رفرنس سریع اسکی‌داک را می‌توانید در https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[اینجا] پیدا کنید. -We've also moved to keeping the translations in separate repositories rather than subdirectories of the English repository. -See link:CONTRIBUTING.md[the Contributing document] for more information. +ما، همچنین، انتقالی انجام دادیم تا ترجمه‌ها را در مخزن‌های جدایی به جای پوشه‌هایی در مخزن انگلیسی نگه‌داری کنیم. +برای اطلاعات بیشتر به link:TRANSLATING.md[سند ترجمه] مراجعه کنید. -== How To Generate the Book +== چگونگی ساختن کتاب -You can generate the e-book files manually with Asciidoctor. -If you run the following you _may_ actually get HTML, Epub, Mobi and PDF output files: +شما می‌توانید فایل‌های این کتاب الکترونیک را به طور دستی با اسکی‌داکتر بسازید. +اگر دستورات پیش‌رو را اجرا کنید _احتمالاً_ می‌توانید خروجی‌های اچ‌تی‌ام‌ال، ای-پاب، موبی و پی‌دی‌اف بگیرید: ---- $ bundle install @@ -32,27 +30,32 @@ Converting to PDF... -- PDF output at progit.pdf ---- -An alternative to calling the `bundle` command is to call directly the `asciidoctor` command. +== ارجاع یک مشکل -Use the following commands: +قبل از ارجاع یک مشکل، لطفاً بررسی کنید که پیشتر مشکل مشابهی در سیستم رهگیری باگ وجود نداشته باشد. ----- -$ asciidoctor progit.asc -$ asciidoctor-pdf progit.asc -$ asciidoctor-epub3 progit.asc -$ asciidoctor-epub3 -a ebook-format=kf8 progit.asc ----- +همچنین اگر این مشکل سابقاً روی سایت رسمی گیت مشاهده شده، لطفاً بازنگری کنید که آیا هنوز در این مخزن موجود است یا خیر. +ممکن است پیش از این مشکل اصلاح شده باشد، اما تغییرات هنوز اعمال نشده باشند. + +=== مشکل فونت فارسی + +در بعضی سیستم‌ها ممکن است خروجی پی‌دی‌اف خوانا نباشد و یا مشکلات قالبی (راست‌چین بودن) و... داشته باشد. +پیشنهاد می‌شود که اسکی‌داکتر را بازتنظیم کنید و از فونت‌سازگار استفاده کنید. + +با توجه به دشواری بازتنظیمی اسکی‌داکتر ممکن است بخواهید از خروجی اچ‌تی‌ام‌ال استفاده کرده یا در صورت نیاز به پی‌دی‌اف، خروجی اچ‌تی‌ام‌ال را توسط ابزاری مانند مرورگر به پی‌دی‌اف تبدیل کنید. -Both use the `asciidoctor`, `asciidoctor-pdf` and `asciidoctor-epub` projects. +=== ترجمهٔ ناقص +ممکن است ترجمه‌ها پیش‌نویس یا ناقص و یا کلمات یکپارچگی نداشته باشند. این امر ممکن است به دلایل مختلف (محدودیت‌های فنی) اتفاق افتاده باشد. اگر چنین موردی مشاهده کردید و در تودو ذکر نشده بود یا برای +آن ایشوی نظیری وجود نداشت یا آنرا حل کرده و پول ریکوئست درست کنید و یا در ایشوهای به ما یادآوری کنید تا در اسرع وقت آنرا پیگیری کنیم. -== Signaling an Issue +به طور کل فایل‌های بالای ۸۰ درصد در فایل استاتوس.جی‌سان کامل تلقی می‌شوند. +فایل‌های ۹۵ درصد ترجمهٔ نهایی شده‌اند و نیازمند بازبینی هستند و فایل‌های ۹۰ درصد پیش‌نویس نهایی هستند. -Before signaling an issue, please check that there isn't already a similar one in the bug tracking system. +=== لینک‌های انگلیسی یا ناقص -Also, if this issue has been spotted on the git-scm.com site, please cross-check that it is still present in this repo. -The issue may have already been corrected, but the changes have not been deployed yet. +ترجمهٔ لینک‌ها و اتصال آنها کار دشواری است. به همین دلیل این کار در مراحل آخر اصلاح خواهد شد. لطفاً شکیبا باشید. -== Contributing +== همکاری -If you'd like to help out by making a change or contributing a translation, take a look at the link:CONTRIBUTING.md[contributor's guide]. +اگر مایلید کمک کنید تا تغییری ایجاد شود، لطفاً به link:CONTRIBUTING.md[راهنمای همکاری] مراجعه کنید. diff --git a/Rakefile b/Rakefile index 41d0cd501..e3a7442a2 100644 --- a/Rakefile +++ b/Rakefile @@ -1,21 +1,34 @@ namespace :book do desc 'build basic book formats' task :build do - puts "Converting to HTML..." - `bundle exec asciidoctor progit.asc` - puts " -- HTML output at progit.html" - puts "Converting to EPub..." - `bundle exec asciidoctor-epub3 progit.asc` - puts " -- Epub output at progit.epub" + begin + version_string = ENV['TRAVIS_TAG'] || `git describe --tags`.chomp + if version_string.empty? + version_string = '0' + end + date_string = Time.now.strftime("%Y-%m-%d") + params = "--attribute revnumber='#{version_string}' --attribute revdate='#{date_string}'" + puts "Generating contributors list" + `git shortlog -s | grep -v -E "(Straub|Chacon)" | cut -f 2- | column -c 120 > book/contributors.txt` - puts "Converting to Mobi (kf8)..." - `bundle exec asciidoctor-epub3 -a ebook-format=kf8 progit.asc` - puts " -- Mobi output at progit.mobi" + puts "Converting to HTML..." + `bundle exec asciidoctor #{params} -a data-uri progit.asc` + puts " -- HTML output at progit.html" - puts "Converting to PDF... (this one takes a while)" - `bundle exec asciidoctor-pdf progit.asc 2>/dev/null` - puts " -- PDF output at progit.pdf" + puts "Converting to EPub..." + `bundle exec asciidoctor-epub3 #{params} progit.asc` + puts " -- Epub output at progit.epub" + + puts "Converting to Mobi (kf8)..." + `bundle exec asciidoctor-epub3 #{params} -a ebook-format=kf8 progit.asc` + puts " -- Mobi output at progit.mobi" + + puts "Converting to PDF... (this one takes a while)" + `bundle exec asciidoctor-pdf #{params} progit.asc 2>/dev/null` + puts " -- PDF output at progit.pdf" + + end end end diff --git a/TRANSLATING.md b/TRANSLATING.md new file mode 100644 index 000000000..1ed7e45a7 --- /dev/null +++ b/TRANSLATING.md @@ -0,0 +1,119 @@ +# ترجمه پرو گیت ویرایش دوم + +ترجمه‌ها به روش غیرمتمرکز مدیریت می‌شوند. هر تیم ترجمه پروژه خودشان را دارند، تیم +پرو گیت صرفاً تغییرات را پول می‌کند و هنگامی که آماده بود در وبسایت رسمی گیت می‌سازد. + +## راهنمای عمومی برای ترجمهٔ پرو گیت + +پرو گیت کتابی دربارهٔ یک ابزار فنی است، در نتیجه ترجمه‌اش در قیاس با یک ترجمه +غیرفنی دشوار است. + +راهنمای زیر را مطالعه کنید تا در راهتان کمکتان کند: +* قبل از اینکه شروع کنید تمام کتاب را در زبان انگلیسی بخوانید تا دربارهٔ محتوایش آگاه باشید و به نحوه نگارش آن عادت کرده باشید. +* مطمئن باشید که دانش فعالی دربارهٔ گیت دارید تا توضیح اصطلاحات فنی برایتان ممکن باشد. +* به یک استاندارد رایج و واحد برای ترجمه وفادار بمانید. +* مطمئن باشید که مفاهیم پایه [قالب‌بندی اسکی‌داک](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/) را خوانده‌اید و می‌فهمید. پیروی نکردن از سینتکس اسکی‌داک می‌تواند منجر به مشکلات در ساخت/کامپایل پی‌دی‌اف، ای‌پاب و اچ‌تی‌ام‌ال مورد نیاز کتاب شود. + +## ترجمه کتاب به زبانی دیگر + +### کمک به پروژه‌ای از پیش موجود + +* جدول زیر را به دنبال یک پروژهٔ از پیش موجود بگردید. +* به صفحهٔ پروژه در گیت‌هاب بروید. +* یک ایشو باز کنید، خود را معرفی کنید و بپرسید که چگونه می‌توانید کمک کنید. + +| Language | GitHub page | +| :------------- | :------------- | +| العربية | [progit2-ar/progit2](https://github.com/progit2-ar/progit2) | +| Беларуская | [progit/progit2-be](https://github.com/progit/progit2-be) | +| български език | [progit/progit2-bg](https://github.com/progit/progit2-bg) | +| Čeština | [progit-cs/progit2-cs](https://github.com/progit-cs/progit2-cs) | +| English | [progit/progit2](https://github.com/progit/progit2) | +| Español | [progit/progit2-es](https://github.com/progit/progit2-es) | +| فارسی | [progit2-fa/progit2](https://github.com/progit2-fa/progit2) | +| Français | [progit/progit2-fr](https://github.com/progit/progit2-fr) | +| Deutsch | [progit/progit2-de](https://github.com/progit/progit2-de) | +| Ελληνικά | [progit2-gr/progit2](https://github.com/progit2-gr/progit2) | +| Indonesian | [progit/progit2-id](https://github.com/progit/progit2-id) | +| Italiano | [progit/progit2-it](https://github.com/progit/progit2-it) | +| 日本語 | [progit/progit2-ja](https://github.com/progit/progit2-ja) | +| 한국어 | [progit/progit2-ko](https://github.com/progit/progit2-ko) | +| Македонски | [progit2-mk/progit2](https://github.com/progit2-mk/progit2) | +| Bahasa Melayu| [progit2-ms/progit2](https://github.com/progit2-ms/progit2) | +| Nederlands | [progit/progit2-nl](https://github.com/progit/progit2-nl) | +| Polski | [progit2-pl/progit2-pl](https://github.com/progit2-pl/progit2-pl) | +| Português (Brasil) | [progit/progit2-pt-br](https://github.com/progit/progit2-pt-br) | +| Русский | [progit/progit2-ru](https://github.com/progit/progit2-ru) | +| Slovenščina | [progit/progit2-sl](https://github.com/progit/progit2-sl) | +| Српски | [progit/progit2-sr](https://github.com/progit/progit2-sr) | +| Svenska | [progit2-sv/progit2](https://github.com/progit2-sv/progit2) | +| Tagalog | [progit2-tl/progit2](https://github.com/progit2-tl/progit2) | +| Türkçe | [progit/progit2-tr](https://github.com/progit/progit2-tr) | +| Українська| [progit/progit2-uk](https://github.com/progit/progit2-uk) | +| Ўзбекча | [progit/progit2-uz](https://github.com/progit/progit2-uz) | +| 简体中文 | [progit/progit2-zh](https://github.com/progit/progit2-zh) | +| 正體中文 | [progit/progit2-zh-tw](https://github.com/progit/progit2-zh-tw) | + +### شروع یک ترجمه جدید + +اگر ترجمه‌ای در زبان شما نیست، می‌توانید ترجمه خودتان را شروع کنید. + +پایه خود را روی دومین ویرایش کتاب که در [اینجا](https://github.com/progit/progit2) موجود است قرار دهید. برای این کار: + 1. [کد ایزو ۶۳۹](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) صحیح زبانتان را انتخاب کنید. + 1. یک [سازمان گیت‌هابی](https://help.github.com/articles/creating-a-new-organization-from-scratch/) با کد مرحله قبل روی گیت‌هاب بسازید. + 1. یک پروژه با نام پروگیت۲ در آن بسازید: ``progit2`` + 1. ساختار این پروژه را در پروژه خود کپی کرده و شروع به ترجمه کنید. + +### بروزرسانی وضعیت ترجمه‌تان + +روی سایت گیت ترجمه‌ها به سه رده تقسیم شده‌اند. هرگاه که به یکی از این سه رده +رسیدید یکی از توسعه‌دهندگان وبسایت گیت را خبر کنید تا تغییرات را پول کنند. + +| رده | کمال | +| :------------- | :------------- | +| ترجمه شروع شده | مقدمه ترجمه شده و دیگر هیچ. | +| به طور ناقص ترجمه شده | تا ۶ فصل ترجمه شده است. | +| ترجمه کامل موجود است |کتاب (تقریباً) به طور کامل ترجمه شده است. | + +## یکپارچه‌سازی مداوم با تراویس سی‌آی + +تراویس سی‌آی یک سرویس [یکپارچه‌ساز +مداوم](https://en.wikipedia.org/wiki/Continuous_integration) است که با گیت‌هاب +یکپارچه‌سازی می‌کند. تراویس سی‌آی برای اطمینان از اینکه پول-رکوئست برای ساختن یا کامپایل +مشکل‌ساز نمی‌شود استفاده می‌شود. تراویس سی‌آی همچنین نسخه کامپایل‌شدهٔ کتاب را ارائه می‌کند. + +راه‌اندازی تراویس سی‌آی نیازمند دسترسی سطح ادمین به مخزن است. + +### ثبت‌نام برای یکپارچه‌سازی مداوم با تراویس سی‌آی + +1. راه‌اندازی یک اکانت تراویس از [اینجا](https://travis-ci.org/). +1. ثبت پروژه‌تان در تراویس لطفاً برای اطلاعات بیشتر [مستندات تراویس](https://docs.travis-ci.com/) را مطالعه کنید. + +### آماده‌سازی مخزنتان برای یکپارچه‌سازی مداوم + +تراویس سی‌آی با اسکن کردن روت پروژه به دنبال فایلی با نام روبرو کار می‌کند: `.travis.yml` + +این فایل شامل «دستور کار» تراویس است و خبر خوب اینکه از پیش یک فایل فعال در سورس پرو +گیت دو در [اینجا](https://raw.githubusercontent.com/progit/progit2-pub/master/travis.yml) هست. + +## راه‌اندازی یک زنجیره انتشار برای این کتاب الکترونیک + +این کار فنی است، لطفا به آیدی روبرو برای شروع کار انتشار ای‌پاب مراجعه کنید: @jnavila + +## فرای پرو گیت + +ترجمهٔ کتاب قدم اول است. وقتی که ترجمه تمام شد، می‌توانید به ترجمهٔ رابط کاربری خود +گیت فکر کنید. + +چنین کاری دانش فنی بیشتری از ابزار کتاب احتیاج دارد. +در بهترین حالت بعد از ترجمه کردن تمام مطالب کتاب، شما قادر خواهید بود که +اصطلاحات درون نرم‌افزار را درک کنید. +اگر احساس می‌کنید از لحاظ فنی آمادگی دارید، [این +مخزنی](https://github.com/git-l10n/git-po) که به دنباش می‌گردید و فقط کافیست که +[این راهنما](https://github.com/git-l10n/git-po/blob/master/po/README) را دنبال کنید. + +اگرچه آگاه باشید که: + + * نیازمند ابزارهای خاص بیشتری خواهید بود تا فایل‌های ترجمهٔ پو را مدیریت و مرج کنید (ابزاری مانند [پوادیت](https://poedit.net/)). ممکن است نیازمند کامپایل گیت شوید تا کار خود را چک کنید. + * دانش پایه‌ای از اینکه چگونه ترجمه نرم‌افزار پیش می‌رود احتیاج خواهید داشت چرا که بسیار با ترجمه کتاب‌ها متفاوت است. + * پروژه اصلی گیت بیشتر از [روش‌های سخت‌گیرانه‌تری](https://github.com/git-l10n/git-po/blob/master/Documentation/SubmittingPatches) برای تأیید همکاری‌ها استفاده می‌کند. مطمئن باشید که از آنها تبعیت می‌کنید. diff --git a/TRANSLATION_NOTES.asc b/TRANSLATION_NOTES.asc index e405dc6a3..29730eddc 100644 --- a/TRANSLATION_NOTES.asc +++ b/TRANSLATION_NOTES.asc @@ -10,6 +10,9 @@ * همچنان که متن ترجمه می‌شود، لطفاً فایل جی‌سان استاتوس را بروزرسانی کنید تا درصد احتمالی اینکه هر فایل به چه مقدار ترجمه شده است قابل تخمین باشد. این تخمین روی صفحات مختلف نمایش داده می‌شود تا خوانندگان بدانند چه مقدار از کار باقی مانده است. +به طور کل فایل‌های بالای ۸۰ درصد در فایل استاتوس.جی‌سان کامل تلقی می‌شوند. +فایل‌های ۹۵ درصد ترجمهٔ نهایی شده‌اند و نیازمند بازبینی هستند و فایل‌های ۹۰ درصد پیش‌نویس نهایی هستند. + === استاندارد نگارشی * تلاش بر آن باشد که هرگز خطی از ۲۰۰ حرف تجاوز نکند. @@ -56,6 +59,8 @@ |=== |واژه یا عبارت |معادل احتمالی انگلیسی + +|??? |Fast-Forward |کنترل نسخه |Version Control |ساب‌ورژن |Subversion |چک‌اوت |Checkout @@ -70,7 +75,8 @@ |آینه |Mirror |کامپایل |Compile |کامپیوتر |Computer -|آپشن |Flag/Option (e.g:--global) +|آپشن |Option (e.g:--global) +|کلید |Flag/Switch (e.g:--global) |گزینه |Option |پیکربندی |Configuration |دستور گیت کانفیگ |git config Command @@ -87,4 +93,17 @@ |نشانگر |Pointer |آبجکت |Object |والد |Parent +|بلاب |Blob +|روت |Root +|متادیتا |Metadata +|انتقال به برنچ |Switch to a/the branch +|تعویض برنچ |Branch switching +|ریورت |Revert +|ایشو |Issue +|درپی-ریموت |Remote-Tracking +|مرجع ریموت |Remote refrence +|بالادست |Upstream +|برنچ پیگیر |Tracking Branch +|ریبیس |Rebase +|دوشاخه |Divergent |=== diff --git a/book/01-introduction/1-introduction.asc b/book/01-introduction/1-introduction.asc deleted file mode 100644 index f095c0f33..000000000 --- a/book/01-introduction/1-introduction.asc +++ /dev/null @@ -1,25 +0,0 @@ -[[_getting_started]] -== آغاز - -این فصل راجع به آغاز به کار با Git خواهد بود. در آغاز پیرامونِ تاریخچه‌یِ ابزارهایِ کنترلِ نسخه توضیحاتی خواهیم داد، -سپس به چگونگیِ راه‌اندازی Git بر رویِ سیستم‌تان خواهیم پرداخت، و در پایان به تنظیمِ Git و کار با آن. -در پایانِ این فصل خواننده علتِ وجود و استفاده از Git را خواهد دانست، و خواهد توانست محیطِ کار با Git را فراهم کند. - -include::sections/about-version-control.asc[] - -include::sections/history.asc[] - -include::sections/basics.asc[] - -include::sections/command-line.asc[] - -include::sections/installing.asc[] - -include::sections/first-time-setup.asc[] - -include::sections/help.asc[] - -=== چکیده - -با مطالعه‌یِ این فصل شما باید مختصراً بدانید Git چیست و چه تفاوتی با سامانه‌یِ کنترلِ نسخه‌یِ مرکزی دارد، که احتمالاً از آن استفاده می‌کرده‌اید. -همچنین شما باید نسخه‌ای آماده به کار از Git را روی سیستم خود داشته باشید که شناسه‌یِ شخصیِ شما بر رویِ آن تنظیم شده‌است. اکنون زمانِ یادگیریِ بنیان‌هایِ Git است. \ No newline at end of file diff --git a/book/01-introduction/sections/about-version-control.asc b/book/01-introduction/sections/about-version-control.asc index a1af9c0de..17de3e240 100644 --- a/book/01-introduction/sections/about-version-control.asc +++ b/book/01-introduction/sections/about-version-control.asc @@ -1,55 +1,69 @@ -=== کنترل نسخه +=== دربارهٔ کنترل نسخه (((version control))) -کنترل نسخه چیست و چرا باید بدان پرداخت؟ کنترل نسخه ساز و کاری است که تغییرات و دگرگونی ها را به مرور زمان نگهداری میکند و شما می توانید در هر زمانی به نسخه و نگارش خاصی برگردید. -ما در این کتاب به کنترل نسخه های کدها و سورسهای نرم افزاری می پردازیم ولی به راستی شما می توانید همه ی گونه های فایلها را کنترل نسخه کنید. +«کنترل نسخه» چیست و چرا باید بدان پرداخت؟ کنترل نسخه سیستمی است که تغییرات را در فایل یا دسته‌ای از +فایل‌ها ذخیره می‌کند و به شما این امکان را می‌دهد که در آینده به نسخه و نگارش خاصی برگردید. +برای مثال‌های این کتاب شما از سورس کد نرم‌افزار به عنوان فایل‌هایی که نسخه آنها کنترل می‌شود استفاده می‌کنید. +اگرچه در واقع می‌توانید تقریباً از هر فایلی استفاده کنید. -اگر شما یک گرافیست یا طراح وب هستنید و می خواهید نسخه های متفاوت از عکس ها و کارهای خود را ( ) نگهداری کنید، سامانه ی کنترل نسخه (VCS) یک گزینه خردمندانه است. VCS به شما امکان برگشت دادن فایل ها یا حتی کل پروژه به وضعیت قبل را میدهد. - همچنین می توانید تغییرات را با مقایسه کردن نسخه ها به سادگی ببینید. آخرین تغییرات (که منجر به خطا شده است) را چه کسی انجام داده است. چه کسی و کی مسئله و مشکلی را مطرح کرده است و از این دست امکانانت. -بکار گیری یک VCS همچنین به این معناست که اگر شما در حین کار پروژه را خراب کردید و فایلهایی به اشتباه از دست رفت، شما به سادگی می توانید پروژه و کارهای انجام شده را بازیابی نمایید. تمام این امکانات با ازاء مقدار بسیار کمی سربار پروژه است. +اگر شما یک گرافیست یا طراح وب هستید و می‌خواهید نسخه‌های متفاوت از عکس‌ها و قالب‌های خود داشته باشید (که احتمالاً می‌خواهید)، یک سیستم کنترل نسخه (Version Control System (VCS)) انتخاب خردمندانه‌ای است. +یک VCS به شما این امکان را می‌دهد که فایل‌های انتخابی یا کل پروژه را به یک حالت قبلی خاص برگردانید، روند تغییرات را بررسی کنید، ببینید چه کسی آخرین‌بار تغییری ایجاد کرده که احتمالاً مشکل آفرین شده، +چه کسی، چه وقت مشکلی را اعلام کرده و... +استفاده از یک VCS همچنین به این معناست که اگر شما در حین کار چیزی را خراب کردید و یا فایل‌هایی از دست رفت، به سادگی می توانید کارهای انجام شده را بازیابی نمایید. +همچنین مقداری سربار به فایل‌های پروژه‌تان افزوده می‌شود. -==== سامانه های کنترل نسخه ی محلی +==== سیستم‌های کنترل نسخهٔ محلی (((version control,local))) -بیاری از کنترل نسخه کردن ها توسط مردم به سادگی با رونوشت گیری از کل فایلها در پوشه ای دیگرا نجام می گیرد. (که اگر خیلی هنر کده باشند نام پوشه ها متناظر با زمان خواهد بود) -این رویکرد بسیار کاربرد دارد چون ساده است. اما بسیار بسیار امکان خطار در این روش وجود دارد. به راختی فراموش می کنیم که روی کدام پوشه کار می کردیم و پوشه را اشتباهی تغییر می دهیم یا رونوشتی اشتباه گرفته می شود. +روش اصلی کنترل نسخهٔ کثیری از افراد کپی کردن فایل‌ها به پوشه‌ای دیگر است (احتمالاً با تاریخ‌گذاری، اگر خیلی باهوش باشند). +این رویکرد به علت سادگی بسیار رایج است هرچند خطا آفرینی بالایی دارد. +فراموش کردن اینکه در کدام پوشه بوده‌اید و نوشتن اشتباهی روی فایل یا فایل‌هایی که نمی‌خواستید روی آن بنویسید بسیار ساده است. -در چالش با این مباحث و مسائل، برنامه نویسان پیشتر از این VCS های محلی و فردی را ساختند که یک پایگاه داده ی ساده داشته که تمام تغییرات را نگهداری می کرده است. +برای حل این مشکل، سال‌ها قبل VCSهای محلی را توسعه دادند که پایگاه داده‌ای ساده داشت که تمام تغییرات فایل‌های تحت مراقبتش را نگهداری می‌کرد. -.Local version control. +.کنترل نسخه محلی. image::images/local.png[Local version control diagram] -یکی از شناخته شده ترین ابزاری های کنترل نسخه، سامانه ای است به نام RCS که امروزه در بسیار از کامپیوترها توزیع شده است. مثلا در سیستم عامل معروف Mac OS X اگر ابزارهای توسعه دهنده (Developer Tools) را نصب کنیم. خط فرمان rcs نیز نصب خواهد شد. -روش کار RCS، نگه داشتن مجموعه ای از وصله ها ( وصله ها همان تفاوت های بین نگارشهای گوناگون فایلها هستند) در ساختاری ویژه است. - در این روش با چسباندن مجموعه ی مشخصی از این وصله ها به هم می توان نسخه ای از فایل را که مربوط به هر زمان دلخواه است دوباره ایجاد کرد. +یکی از شناخته‌شده‌ترین ابزاری‌های کنترل نسخه، سیستمی به نام RCS بود که حتی امروز، با بسیاری از کامپیوترها توزیع می‌شود. +https://www.gnu.org/software/rcs/[RCS] با نگه داشتن مجموعه‌هایی از پچ‌ها (Patch/وصله) -- همان تفاوت‌های بین نگارش‌های گوناگون فایل‌ها -- در قالبی ویژه کار می‌کند؛ +پس از این، با اعمال پچ‌ها می‌تواند هر نسخه‌ای از فایل که مربوط به هر زمان دلخواه است را بازسازی کند. -==== سامانه های کنترل نسخه ی متمرکز +==== سیستم‌های کنترل نسخه ی متمرکز (((version control,centralized))) -چالش بزرگ دیگری که مردم با آن روبرو می شوند نیاز به همکاری با توسعه دهندگانی است که با سیستمهای دیگر کار می کنند. در برخود با این چالش سامانه های کنترل نسخه ی متمرکز (CVCSs) ایجاد شده اند. - این سامانه ها چون CVS، Subversion و Preforce یک سرور دارند که تمام نگارشهای فایلها را در بر دارد و تعدادی مشتری یا خدمت گیرنده دارند که فایل ها را از سرور جهت انجام تغییرات به امانت می گیرند. سالهای سال این روش استاندارد کنترل نسخه بوده است. +چالش بزرگ دیگری که مردم با آن روبرو می شوند نیاز به همکاری با توسعه‌دهندگانی است که با سیستم‌های دیگر کار می‌کنند. +دربرخورد با این چالش سیستم‌های کنترل نسخه متمرکز (Centralized Version Control System (CVCS)) ایجاد شدند. +این قبیل سیستم‌ها (چون CVS، ساب‌ورژن و Preforce) یک سرور دارند که تمام فایل‌های نسخه‌بندی شده را در بر دارد و تعدادی کلاینت (Client/خدمت‌گیرنده) +که فایل‌هایی را از آن سرور چک‌اوت (Checkout/وارسی) می‌کنند. (((CVS)))(((Subversion)))(((Perforce))) سال‌های سال این روش استاندارد کنترل نسخه بوده است. -.Centralized version control. +.کنترل نسخه متمرکز. image::images/centralized.png[Centralized version control diagram] -این ساماندهی به ویژه برای VCS های محلی منافع و مزایایی دارد. برای نمونه هرکسی به میزان کنترل شده ای از فعالیت های دیگران روی پروژه آگاهی پیدا می کند. مدیریان دسترسی و کنترل مناسبی بر این دارند که چه کسی چه کاری می تواند انجام دهد. -همچنین اداره کردن یک کنترل نسخه ی مرکزی () بسیار ساده تر از درگیر بودن با پایگاه داده محلی روی کلاینت هاست. -به هر روی ، این گونه ساماندهی برخی پالشهای بنیادینی نیز دارد. آشکارترین آن رخدادن خطا در سروری که نسخه ها در آن متمرکز شده است. - اگر سرور برای یک ساعت دجار اختلال شود، در طول این یک ساعت هیچ کس نمی تواند تغییراتی که انجام داده و کارهایی که کرده است را ذخیره نماید. -اگر فضای ذخیره سازی سرور دچار مشکل شود و پشتیبان مناسبی هم تهیه نشده باشد همه چیز (تاریخچه کامل پروژه بجز آنچه یک خدمت گیرنده روی کامپیوتر محلی خود ذخیره کرده است) از دست خواهد رفت. - VCS های محلی نیز همگی از این مشکل را دارند. هرگاه شما کل تاریخچه ی پروژه را یک جا نگه داری کنید، خطر از دست دادن کل پروژه وجود دارد. +این ساماندهی به ویژه برای VCSهای محلی منافع و مزایای بسیاری دارد. به طور مثال هر کسی به میزان مشخصی از فعالیت‌های دیگران روی پروژه آگاهی دارد. +مدیریان دسترسی و کنترل مناسبی بر این دارند که چه کسی چه کاری می تواند انجام دهد؛ +همچنین مدیریت یک CVCS خیلی آسان‌تر از درگیری با پایگاه‌داده‌های محلی روی تک تک کلاینت‌هاست. -==== سامانه های کنترل نسخه توزیع شده +هرچند که این گونه ساماندهی معایب جدی نیز دارد. واضح‌ترین آن رخدادن خطا در سروری که نسخه‌ها در آن متمرکز شده است. +اگر که سرور برای یک ساعت غیرفعال باشد، در طول این یک ساعت هیچ‌کس نمی تواند همکاری یا تغییراتی که انجام داده است را ذخیره نماید. +اگر هارددیسک سرور مرکزی دچار مشکلی شود و پشتیبان مناسبی هم تهیه نشده باشد +همه چیز (تاریخچه کامل پروژه بجز اسنپ‌شات‌هایی که یک کلاینت ممکن است روی کامپیوتر خود ذخیره کرده باشد) از دست خواهد رفت. +VCSهای محلی نیز همگی این مشکل را دارند -- هرگاه کل تاریخچه پروژه را در یک مکان واحد ذخیره کنید، خطر از دست‌دادن همه چیز را به جان می‌خرید. + +==== سیستم‌های کنترل نسخه توزیع‌شده (((version control,distributed))) -اینجا است که سیستم‌های کنترل نسخه پخشی (DVCSs) نمود پیدا می‌کنند. در یک DVCS (مانند Git، Mercurial، Bazaar یا Darcs) کابران به checkout کردن آخرین تصویر لحظه‌ای فایل‌ها اکتفا نمی‌کنند: آن‌ها مخزن را نیز به‌صورت کامل کپی می‌کنند. بنابراین اگر هر سروری که سیستم‌ها به واسطه آن در حال تعامل با یکدیگر هستند متوقف و از کار بیافتد، با کپی مخرن هر کدام از کاربران برروی سرور، عمل بازیابی انجام می‌گیرد. در واقع هر clone ای، پشتیبان کاملی از تمامی داده‌ها است. +اینجا است که سیستم‌های کنترل نسخه توزیع‌شده (Distributed Version Control System (DVCS)) نمود پیدا می‌کنند. +در یک DVCS (مانند گیت، Mercurial، Bazaar یا Darcs) کلاینت‌ها صرفاً به چک‌اوت کردن آخرین اسنپ‌شات فایل‌ها اکتفا نمی‌کنند؛ +بلکه آن‌ها کل مخزن (Repository) را کپی عینی یا آینه (Mirror) می‌کنند که شامل تاریخچه کاملش هم می‌شود. +بنابراین اگر هر سروری که سیستم‌ها به واسطه آن در حال تعامل با یکدیگر هستند متوقف و از کار بیافتد، با کپی مخرن هر کدام از کاربران بر روی سرور، می‌توان آن را بازیابی کرد. +در واقع هر کلون، پشتیبان کاملی از تمامی داده‌ها است. -.Distributed version control. +.کنترل نسخه توزیع‌شده. image::images/distributed.png[Distributed version control diagram] -علاوه بر آن اکثر این سیستم‌ها تعامل خوبی با داشتن مخازن خارجی متعدد جهت کار کردن با آن‌ها دارند، در نتیجه شخص خواهد توانست با گروه‌های مختلفی در قالب پروژه‌ای یکسان به‌صورت همزمان تعامل داشته باشد. این قابلیت این امکان را به کاربر خواهد داد که جریان‌های کاری متنوعی همانند مدل‌های سلسه مراتبی را پیاده سازی کند که انجام آن در سیستم‌های متمرکز امکان پذیر نیست. - - +علاوه بر آن اکثر این سیستم‌ها تعامل کاری خوبی با مخازن متعدد خارجی دارند و از آن استقبال می‌کنند، +در نتیجه شما می‌توانید با گروه‌های مختلفی به روش‌های مختلفی در قالب پروژه‌ای یکسان به‌صورت همزمان همکاری کنید. +این قابلیت این امکان را به کاربر می‌دهد که چندین جریان کاری متنوع، مانند مدل‌های سلسه مراتبی، را پیاده‌سازی کند که انجام آن در سیستم‌های متمرکز امکان‌پذیر نیست. diff --git a/book/01-introduction/sections/basics.asc b/book/01-introduction/sections/basics.asc deleted file mode 100644 index 5f6d45e4a..000000000 --- a/book/01-introduction/sections/basics.asc +++ /dev/null @@ -1,108 +0,0 @@ -=== Git Basics - -So, what is Git in a nutshell? -This is an important section to absorb, because if you understand what Git is and the fundamentals of how it works, then using Git effectively will probably be much easier for you. -As you learn Git, try to clear your mind of the things you may know about other VCSs, such as CVS, Subversion or Perforce -- doing so will help you avoid subtle confusion when using the tool. -Even though Git's user interface is fairly similar to these other VCSs, Git stores and thinks about information in a very different way, and understanding these differences will help you avoid becoming confused while using it.(((Subversion)))(((Perforce))) - -==== Snapshots, Not Differences - -The major difference between Git and any other VCS (Subversion and friends included) is the way Git thinks about its data. -Conceptually, most other systems store information as a list of file-based changes. -These other systems (CVS, Subversion, Perforce, Bazaar, and so on) think of the information they store as a set of files and the changes made to each file over time (this is commonly described as _delta-based_ version control). - -.Storing data as changes to a base version of each file. -image::images/deltas.png[Storing data as changes to a base version of each file.] - -Git doesn't think of or store its data this way. -Instead, Git thinks of its data more like a series of snapshots of a miniature filesystem. -With Git, every time you commit, or save the state of your project, Git basically takes a picture of what all your files look like at that moment and stores a reference to that snapshot. -To be efficient, if files have not changed, Git doesn't store the file again, just a link to the previous identical file it has already stored. -Git thinks about its data more like a *stream of snapshots*. - -.Storing data as snapshots of the project over time. -image::images/snapshots.png[Git stores data as snapshots of the project over time.] - -This is an important distinction between Git and nearly all other VCSs. -It makes Git reconsider almost every aspect of version control that most other systems copied from the previous generation. -This makes Git more like a mini filesystem with some incredibly powerful tools built on top of it, rather than simply a VCS. -We'll explore some of the benefits you gain by thinking of your data this way when we cover Git branching in <<_git_branching>>. - -==== Nearly Every Operation Is Local - -Most operations in Git need only local files and resources to operate -- generally no information is needed from another computer on your network. -If you're used to a CVCS where most operations have that network latency overhead, this aspect of Git will make you think that the gods of speed have blessed Git with unworldly powers. -Because you have the entire history of the project right there on your local disk, most operations seem almost instantaneous. - -For example, to browse the history of the project, Git doesn't need to go out to the server to get the history and display it for you -- it simply reads it directly from your local database. -This means you see the project history almost instantly. -If you want to see the changes introduced between the current version of a file and the file a month ago, Git can look up the file a month ago and do a local difference calculation, instead of having to either ask a remote server to do it or pull an older version of the file from the remote server to do it locally. - -This also means that there is very little you can't do if you're offline or off VPN. -If you get on an airplane or a train and want to do a little work, you can commit happily (to your _local_ copy, remember?) until you get to a network connection to upload. -If you go home and can't get your VPN client working properly, you can still work. -In many other systems, doing so is either impossible or painful. -In Perforce, for example, you can't do much when you aren't connected to the server; and in Subversion and CVS, you can edit files, but you can't commit changes to your database (because your database is offline). -This may not seem like a huge deal, but you may be surprised what a big difference it can make. - -==== Git Has Integrity - -Everything in Git is check-summed before it is stored and is then referred to by that checksum. -This means it's impossible to change the contents of any file or directory without Git knowing about it. -This functionality is built into Git at the lowest levels and is integral to its philosophy. -You can't lose information in transit or get file corruption without Git being able to detect it. - -The mechanism that Git uses for this checksumming is called a SHA-1 hash.(((SHA-1))) -This is a 40-character string composed of hexadecimal characters (0–9 and a–f) and calculated based on the contents of a file or directory structure in Git. -A SHA-1 hash looks something like this: - -[source] ----- -24b9da6552252987aa493b52f8696cd6d3b00373 ----- - -You will see these hash values all over the place in Git because it uses them so much. -In fact, Git stores everything in its database not by file name but by the hash value of its contents. - -==== Git Generally Only Adds Data - -When you do actions in Git, nearly all of them only _add_ data to the Git database. -It is hard to get the system to do anything that is not undoable or to make it erase data in any way. -As with any VCS, you can lose or mess up changes you haven't committed yet, but after you commit a snapshot into Git, it is very difficult to lose, especially if you regularly push your database to another repository. - -This makes using Git a joy because we know we can experiment without the danger of severely screwing things up. -For a more in-depth look at how Git stores its data and how you can recover data that seems lost, see <<_undoing>>. - -==== The Three States - -Pay attention now -- here is the main thing to remember about Git if you want the rest of your learning process to go smoothly. -Git has three main states that your files can reside in: _committed_, _modified_, and _staged_: - -* Committed means that the data is safely stored in your local database. -* Modified means that you have changed the file but have not committed it to your database yet. -* Staged means that you have marked a modified file in its current version to go into your next commit snapshot. - -This leads us to the three main sections of a Git project: the Git directory, the working tree, and the staging area. - -.Working tree, staging area, and Git directory. -image::images/areas.png["Working tree, staging area, and Git directory."] - -The Git directory is where Git stores the metadata and object database for your project. -This is the most important part of Git, and it is what is copied when you _clone_ a repository from another computer. - -The working tree is a single checkout of one version of the project. -These files are pulled out of the compressed database in the Git directory and placed on disk for you to use or modify. - -The staging area is a file, generally contained in your Git directory, that stores information about what will go into your next commit. -Its technical name in Git parlance is the ``index'', but the phrase ``staging area'' works just as well. - -The basic Git workflow goes something like this: - -1. You modify files in your working tree. -2. You selectively stage just those changes you want to be part of your next commit, which adds _only_ those changes to the staging area. -3. You do a commit, which takes the files as they are in the staging area and stores that snapshot permanently to your Git directory. - -If a particular version of a file is in the Git directory, it's considered committed. -If it has been modified and was 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 <<_git_basics_chapter>>, you'll learn more about these states and how you can either take advantage of them or skip the staged part entirely. diff --git a/book/01-introduction/sections/command-line.asc b/book/01-introduction/sections/command-line.asc index b1dfdabd4..8b0dd8b4f 100644 --- a/book/01-introduction/sections/command-line.asc +++ b/book/01-introduction/sections/command-line.asc @@ -1,11 +1,11 @@ -=== خط فرمان +=== خط فرمان -روشهای مختلفی برای استفاده از گیت وجود دارد. -ابزار اصلی خط فرمان و بسیاری از رابط های کاربری گرافیکی با قابلیت های مختلف وجود دارد. +روش‌های مختلفی برای استفاده از گیت وجود دارد. +ابزارهای اصیل خط فرمان و بسیاری از رابط‌های کاربری گرافیکی با قابلیت‌های مختلف وجود دارد. برای این کتاب، ما از گیت در خط فرمان استفاده خواهیم کرد. -برای یکی، خط فرمان تنها به شما این امکان را می دهد که بتوانید همه دستورات گیت را اجرا کنید - اکثر رابط های گرافیکی کاربری تنها یک بخش جزئی از قابلیت گیت برای ساده سازی اجرای آن هستد. -اگر می دانید که چگونه نسخه خط فرمان را اجرا کنید، احتمالا می توانید از نحوه اجرای نسخه رابط گرافیکی نیز سردربیاورید، اما غیر از این مورد لزوما اینطور نیست. -همچنین، در حالی که انتخاب سرویس دهنده گرافیکی شما یک سلیقه شخصی است، ابزار خط فرمان همه کاربران، نصب شده و در دسترس خواهد بود. +اول آنکه فقط خط فرمان به شما این امکان را می دهد که بتوانید _همه_ دستورات گیت را اجرا کنید -- اکثر رابط‌های گرافیکی جهت ساده بودن فقط بخش جزئی از کارکرد گیت را پیاده‌سازی می‌کنند. +اگر می‌دانید که چگونه نسخه خط فرمان را اجرا کنید، احتمالا می توانید از نحوه اجرای نسخه رابط گرافیکی نیز سر دربیاورید، اما برعکس آن لزوماً ممکن نیست. +علاوه بر آن ممکن است که انتخاب کلاینت گرافیکی حاصل سلیقه شخصی شما باشد، اما _همه_ کاربران همیشه رابط واحد خط فرمان را نصب و در دسترس دارند. -بنابراین ما انتظار داریم شما بدانید که چگونه ترمینال را در مکینتاش یاقسمت فرمان سریع یا قدرت ظاهری در ویندوز باز کنید. -اگر شما نمیدانید که ما در مورد چه چیزی صحبت می کنیم، ممکن است نیاز به توقف داشته باشید و به سرعت تحقیق کنید تا بتوانید بقیه نمونه ها و توصیفهای این کتاب را دنبال کنید. +بنابرین انتظار می‌رود که شما بدانید چگونه ترمینال را در مک و یا Command Prompt یا Powershell را در ویندوز باز کنید. +اگر شما نمی‌دانید که در این بخش، موضوع مورد بحث چیست، شاید نیاز باشد که دست نگه دارید و تحقیقی سریع دربارهٔ این مبحث کنید تا بتوانید ادامه مثال‌ها و توضیحات این کتاب را دنبال کنید. diff --git a/book/01-introduction/sections/first-time-setup.asc b/book/01-introduction/sections/first-time-setup.asc index 5644730d8..f5a0230c7 100644 --- a/book/01-introduction/sections/first-time-setup.asc +++ b/book/01-introduction/sections/first-time-setup.asc @@ -1,32 +1,43 @@ [[_first_time]] -=== اولین زمان راه اندازی گیت +=== اولین راه‌اندازی گیت -حالا که گیت را در سیستم خود دارید، می خواهید چند تغییر در محیط گیت خود انجام دهید. -شما باید این کارها را فقط یک بار در هر رایانه ای انجام دهید؛ سپس هماهنگی های دیگر با بروز رسانی صورت می گیرد. -شما همچنین در هر زمانی که خواستید آنها را با اجرای دستورات دوباره تغییر دهید. +حالا که گیت را در سیستم خود دارید، وقت آن است که چند شخصی‌سازی در محیط گیت‌تان انجام دهید. +شما باید این کارها را فقط یک بار به ازای هر کامپیوتری انجام دهید؛ این تنظیمات با بروزرسانی‌ها از بین نمی‌رود. +همچنین شما می‌توانید هر زمان که خواستید آنها را با اجرای دوباره دستورات تغییر دهید. -گیت با یک ابزار به نام `git config`همراه است که به شما امکان تنظیم کردن متغیرهای پیکربندی را می دهد که تمام جنبه های نحوه عمل گیت را کنترل می کند. (((دستورات گیت ،پیکربندی))) +گیت با ابزاری به نام `git config` ارائه می‌شود که به شما امکان تنظیم و خواندن متغیرهای پیکربندی که تمام جوانب کاری گیت و ظاهر آن را مدیریت می‌کنند را می‌دهد.(((git commands, config))) این متغیرها را می توان در سه مکان مختلف ذخیره کرد: -1. `/etc/gitconfig` file: Contains values applied to every user on the system and all their repositories. - If you pass the option `--system` to `git config`, it reads and writes from this file specifically. - (Because this is a system configuration file, you would need administrative or superuser privilege to make changes to it.) -2. `~/.gitconfig` or `~/.config/git/config` file: Values specific personally to you, the user. - You can make Git read and write to this file specifically by passing the `--global` option. -3. `config` file in the Git directory (that is, `.git/config`) of whatever repository you're currently using: Specific to that single repository. +1. فایل `/etc/gitconfig`: شامل مقادیری است که برای تمام کاربران سیستم و تمام مخازن آنها اعمال می‌شود. +اگر از آپشن `--system` برای `git config` استفاده کنید خواندن و نوشتن با فایل مذکور انجام می‌شود. +(به دلیل اینکه این یک فایل تنظیم سیستمی است ممکن است شما به دسترسی سطح ادمین یا سوپریوزر احتیاج داشته باشید تا بتوانید آن را ویرایش کنید.) +2. فایل `~/.gitconfig` یا `~/.config/git/config`: مقادیر مختص به شما، کاربر، را نگه‌داری می‌کند. +شما می‌توانید با دادن آپشن `--global` به گیت بگویید تا مخصوصاً با این فایل خواندن و نوشتن را انجام بدهد. +3. فایل `config` درون پوشه گیت (همان `.git/config`) هر پروژه‌ای که در حال کار روی آن هستید: تنظیمات مختص به آن مخزن واحد را شامل می‌شود. +شما می‌توانید با آپشن `--local` گیت را مجبور کنید تا خواندن و نوشتن را روی این فایل انجام دهد. لکن درحقیقت به طور پیش‌فرض گیت همین کار را می‌کند. +(بدیهی است که نیاز دارید درون پوشهٔ آن مخزن گیت باشید تا این دستور به درستی کار کند.) -Each level overrides values in the previous level, so values in `.git/config` trump those in `/etc/gitconfig`. +هر کدام از این مرتبه‌ها تنظیمات مرتبه قبل را بازنویسی می‌کنند. بنابراین مقادیر `.git/config` نسبت به مقادیر `/etc/gitconfig` اولویت دارند. -On Windows systems, Git looks for the `.gitconfig` file in the `$HOME` directory (`C:\Users\$USER` for most people). -It also still looks for `/etc/gitconfig`, although it's relative to the MSys root, which is wherever you decide to install Git on your Windows system when you run the installer. -If you are using version 2.x or later of Git for Windows, there is also a system-level config file at -`C:\Documents and Settings\All Users\Application Data\Git\config` on Windows XP, and in `C:\ProgramData\Git\config` on Windows Vista and newer. -This config file can only be changed by `git config -f ` as an admin. +در سیستم‌های ویندوزی گیت به دنبال فایل `.gitconfig` در پوشه `$HOME` می‌گردد (که برای اکثریت `C:\Users\$USER` است). +علاوه بر آن همچنان به دنبال `/etc/gitconfig` می‌گردد، +اگرچه به دنبال آن به نسبت روت MSys می‌گردد که هنگامی نصب گیت روی سیستم ویندوزتان آنرا تنظیم می‌کنید. +اگر از نسخه 2.x یا بالاتر گیت برای ویندوز استفاده می‌کنید باید یک فایل پیکربندی مرتبه-سیستمی +در `C:\Documents and Settings\All Users\Application Data\Git\config` روی ویندوز XP و +در `C:\ProgramData\Git\config` روی ویندوز ویستا و جدیدتر وجود داشته باشد. +این فایل پیکربندی فقط با `git config -f ` به عنوان ادمین قبل ویرایش است. + +شما می‌توانید تمام تنظیمات خود و اینکه از کجا می‌آیند را با دستور زیر بررسی کنید: + +[source,console] +---- +$ git config --list --show-origin +---- ==== هویت شما -اولین چیزی که باید هنگام نصب گیت انجام دهید این است که نام کاربری و آدرس ایمیل خود را تنظیم کنید. -این مهم است، زیرا که هر مشخصه گیت (گیت کامیت) از این اطلاعات استفاده می کند و مسلما به مشخصاتی که وارد می کنید استناد می شود: +اولین کاری که باید هنگام نصب گیت انجام دهید تنظیم نام کاربری و آدرس ایمیل خود است. +این اصل مهمی است چرا که هر گیت کامیت از این اطلاعات استفاده می‌کند و به صورت غیرقابل تغییر درون کامیت‌هایی که شما می‌سازید حک می‌شود: [source,console] ---- @@ -34,55 +45,50 @@ $ git config --global user.name "John Doe" $ git config --global user.email johndoe@example.com ---- -مجددا، اگر گزینه `--global` را گذرانده باشید شما می توانید این کار را فقط یک بار انجام دهید، زیرا از این به بعد گیت همیشه از این اطلاعات برای هر کاری که در آن سیستم انجام می دهید استفاده می کند. -اگر می خواهید نام یا آدرس ایمیل را برای پروژه های خاص تغییر دهید، زمانی که در آن پروژه هستید می توانید فرمان را بدون پارامتر `--global` اجرا کنید. +مجدداً، فقط لازم است که یکبار این کار را انجام دهید (تنها در حالتی که آپشن `--global` را به دستور بدهید)، چرا که گیت همیشه از این اطلاعات برای هر کاری در آن سیستم استفاده خواهد کرد. +اگر می‌خواهید این را با یک نام یا ایمیل متفاوت برای پروژه‌ای خاص بازنویسی کنید، مادامی که در آن پروژه هستید می‌توانید بدون `--global` آنرا اجرا کنید. -بسیاری از ابزارهای رابط گرافیکی کاربر هنگامی که شما برای اولین بار آنها را اجرا می کنید به شما کمک می کنند تا این کار را انجام دهید. +بسیاری از ابزارهای گرافیکی هنگامی که شما برای اولین بار آنها را اجرا می‌کنید، به شما کمک می‌کنند این پیکربندی‌ها را انجام دهید. +[[_editor]] ==== ویرایشگر شما -اکنون که هویت شما تنظیم شده است، می توانید ویرایشگر پیش فرض متن را زمانی که پیامی تایپ می کنید، پیکربندی کنید. -اگر پیکربندی نشده باشد، گیت از ویرایشگر پیش فرض سیستم شما استفاده می کند. +اکنون که هویت شما تنظیم شده است، می‌توانید ویرایشگر پیش‌فرضی که هنگام تایپ پیام، گیت احتیاج دارد را تنظیم کنید. +در صورتی که تنظیم نشود گیت از ویرایشگر پیش‌فرض سیستم استفاده می‌کند. -اگر می خواهید از یک ویرایشگر متنی دیگر مانند ای مکس استفاده کنید، می توانید موارد زیر را انجام دهید: +اگر می‌خواهید که از ویرایشگر متفاوتی، مانند ایمکس، استفاده کنید می‌توانید مانند دستور زیر این کار را انجام دهید: [source,console] ---- $ git config --global core.editor emacs ---- -در سیستم ویندوز، اگر می خواهید از یک ویرایشگر متن استفاده کنید، باید برای فایل اجرایی آن مسیر دقیق را مشخص کنید. -این می تواند با توجه به نوع ویرایشگر شما بسته بندی شود. +در یک سیستم ویندوزی اگر می‌خواهید که از یک ویرایشگر متفاوت استفاده کنید باید مسیر کامل فایل اجرایی آنرا مشخص کنید. +این مسیر می‌تواند بسته به نحوه پکیج‌شدن ویرایشگر شما متفاوت باشد. -در مورد نوت پد++، که یک ویرایشگر برنامه نویسی محبوب است، شما احتمالا می خواهید از نسخه 32 بیتی استفاده کنید، زیرا در هنگام نوشتار، نسخه 64 بیتی تمام پلاگین ها را پشتیبانی نمی کند. -اگر شما یک سیستم ویندوز 32 بیتی، یا یک ویرایشگر 64 بیتی در یک سیستم 64 بیتی دارید، می توانید به این شکل تایپ کنید: +نوت‌پد++ را نظر بگیرید، یک ویرایشگر محبوب برنامه‌نویسی، که از آنجایی که نسخه ۶۴ بیتی در زمان نوشتن این متن از تمام افزونه‌ها پشتیبانی نمی‌کند احتمالاً از نسخه ۳۲ بیت آن استفاده می‌کنید. +اگر شما از یک سیستم ویندوز ۲۳ بیتی استفاده می‌کنید یا یک ویرایشگر ۶۴ بیتی روی یک سیستم ۶۴ بیتی دارید، ورودی مسیر کامل چیزی شبیه زیر خواهد بود: [source,console] ---- -$ git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -multiInst -nosession" ----- - -اگر یک ویرایشگر 32 بیتی در یک سیستم 64 بیتی داشته باشید، برنامه در C: \ Program Files (x86) نصب خواهد شد: - -[source,console] ----- -$ git config --global core.editor "'C:/Program Files (x86)/Notepad++/notepad++.exe' -multiInst -nosession" +$ git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin" ---- [NOTE] ==== -وی ای ام، ای مکس و نوت پد++ ویرایشگرهای متداولی هستند که اغلب توسط توسعه دهندگان بر روی سیستم های مبتنی بر یونیکس (شبکه ای) مانند لینوکس و سیستم عامل مکینتاش و یا ویندوز استفاده می شوند. -اگر با این ویرایشگر ها آشنا نباشید، ممکن است لازم باشد دستورالعمل های خاصی برای نحوه نصب و تنظیم ویرایشگر مورد علاقه خود را با گیت جستجو کنید. +ویم، ایمکس و نوت‌پد++ ویرایشگرهای محبوبی هستند که اکثراً توسط کاربران سیستم‌های یونیکس-پایه مانند لینوکس و مک و یا حتی یک سیستم ویندوزی استفاده می‌شوند. +اگر شما از ادیتور دیگری یا نسخه ۳۲ بیتی استفاده می‌کنید، لطفاً دستورات مختص به اینکه چگونه ویرایشگر مورد علاقه خود را در گیت راه بنیدازید را از <> پیدا کنید. ==== [WARNING] ==== -زمانی که گیت در حال راه اندازی است اگر ویرایشگر خود را به این شکل تنظیم نکنید، ممکن است دچار سردرگمی شوید. +اگر اینگونه ویرایشگر خود را معرفی نکنید ممکن است در هنگام اجرای گیت دچار سردرگمی شوید. +مثلاً حین اجرای مثال‌ها، هنگامی که گیت ویرایشگر را روی یک سیستم ویندوزی فرا می‌خواند ممکن است پیش از اتمام دستور گیت به مشکل بخورد و متوجه نشوید. ==== ==== بررسی تنظیمات شما -اگر می خواهید تنظیمات پیکربندی خود را بررسی کنید، می توانید از دستور "پیکربندی گیت – لیست" برای لیست شدن تمام تنظیمات گیت که در آن نقطه هستند استفاده کنید: +اگر می‌خواهید که تنظیمات پیکربندی خود را بررسی کنید، می‌توانید از دستور `git config --list` برای لیست کردن تمام تنظیماتی که گیت در مکان اجرا پیدا می‌کند استفاده کنید: [source,console] ---- @@ -96,10 +102,10 @@ color.diff=auto ... ---- -شما ممکن است کلیدها را بیش از یک بار ببینید، زیرا گیت همان کلید از فایل های مختلف را می خواند (`/etc/gitconfig` and `~/.gitconfig`, for example). -در این مورد، گیت با استفاده از آخرین ارزش برای هر کلید منحصر به فرد آن می بیند. +شما ممکن است بعضی از کلیدها را بیش از سایر کلیدها ببینید چرا که گیت آن کلیدها را از فایل‌های مختلف می‌خواند (`/etc/gitconfig` و `~/.gitconfig` به طور مثال). +در این حالت گیت از آخرین مقداری که برای هر کلید یکتا می‌خواند استفاده می‌کند. -همچنین می توانید از طریق تایپ کردن آنچه گیت فکر می کند یک مقدار کلیدی خاص را بررسی کنید `git config `:(((git commands, config))) +همچنین می‌توانید مقدار مد نظر گیت را برای یک کلید خاص را با `git cofnig ` بررسی کنید:(((git commands, config))) [source,console] ---- @@ -109,8 +115,9 @@ John Doe [NOTE] ==== -از آنجا که گیت ممکن است مقدار متغیر پیکربندی ثابتی را در بیش از یک فایل بخواند، احتمال دارد که یک مقدار غیر منتظره برای یکی از این مقادیر داشته باشید و چگونگی این قضیه را ندانید. -در مواردی مانند این شما می توانید از گیت به عنوان _مرجع_ برای جستجوی این مقدار استفاده کنید تا به شما دلیل ایجاد آن مقدار را بگوید: + +از آنجا که ممکن است گیت مقدار یک متغییر پیکربندی را از بیش از یک فایل بخواند، احتمال دارد که یک مقدار غیرمنتظره برای یکی از این مقادیر پیدا کنید و چرایی این قضیه را ندانید. +در چنین مواردی می توانید از گیت _origin_ (مرجع) یک مقدار را پرس‌وجو کنید و به شما خواهد گفت که کدام فایل پیکربندی آخرین حرف را در تنظیم مقدار مورد نظر زده است: [source,console] ---- diff --git a/book/01-introduction/sections/help.asc b/book/01-introduction/sections/help.asc index c8017c9dc..af809f638 100644 --- a/book/01-introduction/sections/help.asc +++ b/book/01-introduction/sections/help.asc @@ -1,26 +1,27 @@ [[_git_help]] -=== Getting Help +=== مددخواهی -If you ever need help while using Git, there are two equivalent ways to get the comprehensive manual page (manpage) help for any of the Git commands: +در شرایطی که برای کار با گیت به کمک احتیاج داشتید، سه روش معادل برای گرفتن یک راهنمای مشروح (_manpage_/من‌پیچ/صفحهٔ راهنما) دربارهٔ هر یک از دستورات گیت وجود دارد: [source,console] ---- $ git help +$ git --help $ man git- ---- -For example, you can get the manpage help for the `git config` command by running(((git commands, help))) +به طور مثال می‌توانید صفحهٔ راهنمای دستور `git config` را با اجرای خط زیر ببینید:(((git commands, help))) [source,console] ---- $ git help config ---- -These commands are nice because you can access them anywhere, even offline. -If the manpages and this book aren't enough and you need in-person help, you can try the `#git` or `#github` channel on the Freenode IRC server (irc.freenode.net). -These channels are regularly filled with hundreds of people who are all very knowledgeable about Git and are often willing to help.(((IRC))) +این‌ها دستورات خوبی هستند چرا که می‌توانید در هرکجا، حتی وقتی آفلاین هستید، به آنها دسترسی پیدا کنید. +اگر صفحات راهنما و این کتاب کافی نیستند و شما به کمک فردی احتیاج دارید، می‌توانید به کانال `#git` یا `#github` روی سرور IRC فری‌نود متصل شوید که در https://freenode.net[] واقع است. +معمولاً این کانال‌ها با صدها داوطلب پر شده است که همه دربارهٔ گیت بسیار آگاه و مایل به کمک کردن هستند.(((IRC))) -In addition, if you don't need the full-blown manpage help, but just need a quick refresher on the available options for a Git command, you can ask for the more concise ``help'' output with the `-h` or `--help` options, as in: +آخر اینکه اگر نیازی به یک صفحه راهنمای کامل و جامع ندارید و فقط به یک یادآوری سریع برای آپشن‌های یک دستور احتیاج دارید، می‌توانید از خروجی مختصر آپشن «کمک» بوسیلهٔ `-h` بخواهید که به شما یادآوری کند؛ همانگونه که در مثال زیر آمده: [source,console] ---- @@ -35,12 +36,13 @@ usage: git add [] [--] ... -e, --edit edit current diff and apply -f, --force allow adding otherwise ignored files -u, --update update tracked files + --renormalize renormalize EOL of tracked files (implies -u) -N, --intent-to-add record only the fact that the path will be added later -A, --all add changes from all tracked and untracked files --ignore-removal ignore paths removed in the working tree (same as --no-all) --refresh don't add, only refresh the index --ignore-errors just skip files which cannot be added because of errors --ignore-missing check if - even missing - files are ignored in dry run - --chmod <(+/-)x> override the executable bit of the listed files + --chmod (+|-)x override the executable bit of the listed files ---- diff --git a/book/01-introduction/sections/history.asc b/book/01-introduction/sections/history.asc index 082c88c5a..711661044 100644 --- a/book/01-introduction/sections/history.asc +++ b/book/01-introduction/sections/history.asc @@ -1,20 +1,20 @@ -=== تاریخچه ی کوتاهی از گیت +=== تاریخچهٔ کوتاهی از گیت -همانند اکثر حوادث بزرگ در در زندگی، Git نیز با خلاقیتی مخرب و جنجالی آتشین شروع شد. +به مثل اکثر چیزهای عالی زندگی، گیت نیز با کمی تخریب خلاقانه و جنجالی آتشین شروع شد. -هسته لینوکس پروژه نرم‌افزاری متن باز با وسعت نسبتاً زیادی است. -جهت نگهداری هسته لینوکس برای مدت زمان زیادی (1991 - 2002) تغییرات نرم‌افزاری به واسطه وصله‌ها و فایل‌های بایگانی شده انتقال پیدا می‌کرد. -در سال 2002، پروژه هسته لینوکس شروع به استفاده از سیستم DVCS خصوصی با نام BitKeeper کرد. +هسته لینوکس پروژه‌ای متن-باز با حوزهٔ بسیار وسیعی است.(((Linux))) +برای سال‌ها (۱۹۹۱ - ۲۰۰۲ میلادی) جهت نگهداری هسته لینوکس تغییرات به واسطه پچ‌ها و فایل‌های آرشیو انتقال پیدا می‌کرد. +در سال ۲۰۰۲ پروژه هسته لینوکس شروع به استفاده از DVCS اختصاصی با نام BitKeeper کرد.(((BitKeeper))) -در سال 2005، ارتباط بین مجموعه تیم توسعه دهنده هسته لینوکس و شرکت تجاری توسعه دهنده BitKeeper گسسته شد و وضعیت ابزاری که قبل از آن به صورت رایگان عرضه می‌گشت تغییر پیدا کرد. -این اتفاق زنگ هشداری برای مجموعه تیم توسعه دهنده لینوکس (به خصوص مؤسس لینوکس، لینوس تورلوادز) بود که بر اساس تجربه‌های کسب شده در استفاده از BitKeeper، خود اقدام به تولید نرم افزاری در این زمینه بزنند. -مواردی از اهداف سیستم جدید عبارت بودند از: +در سال ۲۰۰۵ رابطه بین جامعه‌ای که هسته لینوکس را توسعه می‌داد و شرکت تجاری که BitKeeper را توسعه می‌داد بهم خورد و رایگان بودن آن برنامه فسخ شد. +این به جامعهٔ توسعه‌دهنده لینوکس (و به خصوص لینوس توروالدز، خالق لینوکس) هشداری داد تا ابزار خود را بر اساس درس‌هایی که پیشتر با استفاده از BitKeeper گرفته بودند توسعه دهند.(((Linus Torvalds))) +چندی از خواسته‌های سیستم جدید عبارت بودند از: -سرعت -طراحی ساده -پشتیبانی قوی از توسعه غیر خطی (هزاران انشعاب موازی) -کاملاً پخشی -قابلیت کنترل بهینه پروژه‌های بزرگ همانند هسته لینوکس (از نظر سرعت و اندازه داده) +* سرعت +* طراحی ساده +* پشتیبانی قوی از توسعه غیرخطی (هزاران برنچ (Branch/شعبه) موازی) +* کاملاً توزیع‌شده +* قابلیت کنترل بهینه پروژه‌های بزرگ همانند هسته لینوکس (از نظر سرعت و اندازه داده) -از زمان تولد Git در سال 2005، این نرم افزار از نظر استفاده آسان و حفظ اهداف اولیه ذکر شده به تکامل و بلوغ رسیده است. -Git نرم افزاری سریع، بسیار بهینه در مواجه با پروژه‌های بزرگ و حاوی سیستم انشعابی باورنکردنی برای توسعه غیر خطی است (فصل 3). +از زمان تولد گیت در سال ۲۰۰۵، این نرم‌افزار برای ساده بودن و سهولت استفاده تکامل پیدا کرده و به بلوغ رسیده و هنوز این استانداردهای اولیه را حفظ می‌کند. +این نرم‌افزار خارق‌العاده سریع، بسیار بهینه در مواجه با پروژه‌های بزرگ و حاوی سیستم انشعابی باورنکردنی برای توسعه غیرخطی است (مراجعه به <>). diff --git a/book/01-introduction/sections/installing.asc b/book/01-introduction/sections/installing.asc index 229350a04..b50c29f91 100644 --- a/book/01-introduction/sections/installing.asc +++ b/book/01-introduction/sections/installing.asc @@ -1,76 +1,83 @@ === نصب گیت -پیش از اینکه بتوانید از گیت استفاده کنید باید آن را نصب کنید +پیش از اینکه بتوانید از گیت استفاده کنید باید آن را نصب کنید. حتی اگر هم اکنون گیت را نصب شده دارید بهتر است که آن را به آخرین نسخه بروز کنید. شما می توان گیت را به عنوان یک بسته یا توسط نصاب دیگری نصب کنید و یا حتی سورس آن را دانلود کرده و خودتان کامپایل نمایید. [NOTE] ==== -این کتاب با نگارش 2.0.0. از گیت نوشته شده است. -اگرچه بیشتر دستوراتی که ما بکار می بریم باید در نسخه های پیشین نیز جوابگو باشد، شاید برخی از آنها با کمی تقییرات همراه باشند. -از آنجا که گیت در سازگاری با نسخه های پیشین خود بسیار خوب عمل می کند، نسخه های بعد از 2.0 نیز باید این دستورات را پشتیبانی کنند. +این کتاب با نگارش *2.8.0*، از گیت نوشته شده است. +اگرچه بیشتر دستوراتی که ما بکار می بریم باید در نسخه‌های پیشین نیز جوابگو باشد، شاید برخی از آنها با کمی تقییرات همراه باشند یا حتی از کار افتاده باشند. +از آنجا که گیت در سازگاری با نسخه‌های پیشین خود بسیار خوب عمل می کند، نسخه‌های بعد از 2.8 نیز باید این دستورات را پشتیبانی کنند. ==== ==== نصب بر روی لینوکس (((Linux, installing))) -اگر قصد نصب Git بر روی لینوکس به واسطه یک نصاب باینری را دارید، می‌توانید این کار را از طریق ابزار مدیریت بسته های نرم‌افزاری که همراه توزیع موردنظر شما ارائه می‌شود انجام دهید. -اگر توزیع شما Fedora است (یا هر توریع دیگری که بر پایه RPM باشد مثل RHEL و یا CentOS)، می‌توانید از `dnf` استفاده کنید: +اگر به واسطه یک نصاب اجرایی قصد نصب ابزاری پایه گیت را روی لینوکس دارید، به طور عمومی باید بتوانید به وسیله پکیج‌منیجری که با توزیعتان همراه است بتوانید انجام دهید. +به طور مثال اگر توزیع شما فدورا است (یا هر توریع RPM-پایه دیگری مثل RHEL و یا CentOS)، می‌توانید از `dnf` استفاده کنید: [source,console] ---- $ sudo dnf install git-all ---- -اگر توزیع بر پایه ی دبیان، همچون Ubuntu را بکار می گیرید می توانید `apt-get` را امتحان کنید: +یا اگر در حال استفاده از توزیع دبیان-پایه‌ای مثل اوبونتو هستید می توانید `apt` را امتحان کنید: [source,console] ---- -$ sudo apt-get install git-all +$ sudo apt install git-all ---- -برای نسخه های دیگری از سیستم های بر پایه یونیکس روش های نصب در وب سایت گیت به نشانی http://git-scm.com/download/linux[] وجود دارد. +برای گزینه‌های بیشتر می‌توانید دستورات نصب روی توزیع‌های مختلف یونیکس را روی سایت گیت به نشانی http://git-scm.com/download/linux[] پیدا کنید. -==== نصب روی Mac +==== نصب روی مک -(((Mac, installing))) -راه های زیادی برای نصب گیت روی Mac وجود دارد. -شاید ساده ترین راه نصب ابزار خط فرمان Xcode باشد.(((Xcode))) -در نسخه ی Mavericks (10.9) و نسخه های بالاتر به راحتی با دستور '' از خط فرمان می توان این کار را کرد. -اگر گیت را نصب نکرده باشید، مراحل نصب پیش روی شما آورده می شود. +(((macOS, installing))) +راه‌های زیادی برای نصب گیت روی مک وجود دارد. +شاید ساده‌ترین راه نصب ابزارهای خط فرمان Xcode باشد.(((Xcode))) +در نسخهٔ Mavericks (10.9) و یا نسخه‌های بالاتر به راحتی با اجرای 'git' از خط فرمان می توان این کار را کرد. -حنی اگر نسخه های بروزتری را برای نصب نیاز داشته باشید می توان از طریق نصاب باینری این کار را انجام دهید. -نصاب گیت برای macOS در وب سایت گیت به نشانی http://git-scm.com/download/mac[] نگه داری می شود و قابل دریافت است. +[source,console] +---- +$ git --version +---- + +اگر گیت را نصب نداشته باشید، مراحل نصب پیش روی شما آورده می شود. + +اگر نسخه‌های بروزتری را برای نصب نیاز داشته باشید می توان از طریق نصاب اجرایی این کار را انجام دهید. +یک نصاب گیت برای سیستم‌عامل مک توسعه پیدا کرده و در وبسایت گیت به آدرس https://git-scm.com/download/mac[] قرار داده شده است. -.Git macOS Installer. +.نصاب گیت مک. image::images/git-osx-installer.png[Git macOS installer.] -همچنین گیت به عنوان بخشی از گیت هاب در هنگام نصب Mac قابل نصب است. رابط گرافیکی ابزار گیت در آنجا گزینه نصب خط فرمان را نیز دارد. -You can download that tool from the GitHub for Mac website, at http://mac.github.com[]. +همچنین شما می‌توانید به عنوان بخشی از نرم‌افزار گیت‌هاب برای مک گیت را نصب کنید. +ابزار رابط گرافیکی گیت آنها گزینه‌ای دارد که به شما اجازه نصب ابزارهای خط فرمان را نیز می‌دهد. +شما می توانید آن ابزار را از سایت گیت‌هاب برای مک به آدرس https://desktop.github.com[] دانلود کنید. -==== Installing on Windows +==== نصب روی ویندوز -There are also a few ways to install Git on Windows.(((Windows, installing))) -The most official build is available for download on the Git website. -Just go to http://git-scm.com/download/win[] and the download will start automatically. -Note that this is a project called Git for Windows, which is separate from Git itself; for more information on it, go to https://git-for-windows.github.io/[]. +همچنین چند راه برای نصب گیت روی ویندوز وجود دارد.(((Windows, installing))) +رسمی‌ترین نسخه روی وبسایت گیت برای دانلود موجود است. +کافیست به http://git-scm.com/download/win[] مراجه کنید و دانلود شما به طور خودکار شروع می‌شود. +به خاطر داشته باشید که این یک پروژه به نام گیت برای ویندوز است که از خود گیت جداست؛ برای اطلاعات بیشتر در این باره به https://gitforwindows.org[] مراجعه کنید. -To get an automated installation you can use the https://chocolatey.org/packages/git[Git Chocolatey package]. -Note that the Chocolatey package is community maintained. +برای یک نصب تمام خودکار می‌توانید از https://chocolatey.org/packages/git[پکیج گیت چوکو] استفاده کنید. +توجه داشته باشید که پکیج چوکو توسط جامعه توسعه پیدا می‌کند. -Another easy way to get Git installed is by installing GitHub for Windows. -The installer includes a command line version of Git as well as the GUI. -It also works well with Powershell, and sets up solid credential caching and sane CRLF settings.(((Powershell)))(((CRLF)))(((credential caching))) -We'll learn more about those things a little later, but suffice it to say they're things you want. -You can download this from the GitHub for Windows website, at http://windows.github.com[]. +روش آسان دیگری که می‌توانید گیت را نصب کنید با استفاده گیت‌هاب دسکتاپ است. +این نصاب یک نسخه خط فرمانی از گیت را هم در کنار رابط گرافیکی شامل می‌شود. +بعلاوه با Powershell به خوبی کار می‌کند و کش گواهی (Credential) و تنظیمات CRLF را به درستی پیاده‌سازی می‌کند.(((Powershell)))(((CRLF)))(((credential caching))) +درباره این مباحث کمی بعدتر می‌آموزیم ولی پیش از آن فقط بدانید که این‌ها مواردی هستند که شما مایلید داشته باشید. +شما می‌توانید این نصاب را از https://desktop.github.com[وبسایت گیت‌هاب دسکتاپ] دانلود کنید. -==== Installing from Source +==== نصب از سورس -Some people may instead find it useful to install Git from source, because you'll get the most recent version. -The binary installers tend to be a bit behind, though as Git has matured in recent years, this has made less of a difference. +در عین حال شماری از مردم نصب گیت از سورس کد را مفید می‌دانند، چراکه ازین طریق جدیدترین نسخه را خواهید گرفت. +نصاب اجرایی غالباً کمی عقب‌تر می‌ماند؛ اگرچه گیت در سال‌های اخیر بالغ شده است و این اختلاف نسخه کمتر تفاوت فاحشی ایجاد خواهد کرد. -If you do want to install Git from source, you need to have the following libraries that Git depends on: autotools, curl, zlib, openssl, expat, and libiconv. -For example, if you're on a system that has `dnf` (such as Fedora) or `apt-get` (such as a Debian-based system), you can use one of these commands to install the minimal dependencies for compiling and installing the Git binaries: +اگر می‌خواهید که گیت را از سورس نصب کنید، کتاب‌خانه‌های روبرو را که گیت به آنها وابستگی (Dependency) دارد را لازم دارید: autotools، curl، zlib، openssl، expat و libiconv. +برای مثال اگر روی سیستمی کار می‌کنید که `dnf‍` را دارد (مثل فدورا) یا `apt-get` (مثل یک سیستم دیبان-پایه)، وارد کنید: [source,console] ---- @@ -80,40 +87,57 @@ $ sudo apt-get install dh-autoreconf libcurl4-gnutls-dev libexpat1-dev \ gettext libz-dev libssl-dev ---- -In order to be able to add the documentation in various formats (doc, html, info), these additional dependencies are required (Note: users of RHEL and RHEL-derivatives like CentOS and Scientific Linux will have to https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F[enable the EPEL repository] to download the `docbook2X` package): +پیش از اینکه قادر باشید که پرونده‌های با قالب‌های مختلف را اضافه کنید (doc، html، info) باید این وابستگی‌ها را هم داشته باشید. [source,console] ---- -$ sudo dnf install asciidoc xmlto docbook2X getopt -$ sudo apt-get install asciidoc xmlto docbook2x getopt +$ sudo dnf install asciidoc xmlto docbook2X +$ sudo apt-get install asciidoc xmlto docbook2x ---- -Additionally, if you're using Fedora/RHEL/RHEL-derivatives, you need to do this +[NOTE] +==== +کاربران RHEL و مشتقات RHEL مثل CentOS و ساینتیفیک لینوکس برای دانلود بسته `docbook2X` مستلزم https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F[فعال کردن مخزن EPEL] هستند. +==== + +اگر از یک توزیع دبیان-پایه (دبیان/اوبونتو/مشتقات اوبونتو) استفاده می‌کنید، بسته `install-info` را نیز احتیاج دارید: [source,console] ---- -$ sudo ln -s /usr/bin/db2x_docbook2texi /usr/bin/docbook2x-texi +$ sudo apt-get install install-info ---- -due to binary name differences. +اگر از یک توزیع RPM-پایه (فدورا/RHEL/مشتقات RHEL) استفاده می‌کنید، بسته `getopt` را نیز احتیاج دارید (که از قبل روی توزیع‌های دبیان-پایه وجود دارد): + +[source,console] +---- +$ sudo dnf install getopt +---- + +علاوه بر این، اگر شما از فدورا/RHEL/مشتقات RHEL استفاده می‌کنید به علت تفاوت نام فایل‌های اجرایی باید دستور زیر را نیز وارد کنید. + +[source,console] +---- +$ sudo ln -s /usr/bin/db2x_docbook2texi /usr/bin/docbook2x-texi +---- -When you have all the necessary dependencies, you can go ahead and grab the latest tagged release tarball from several places. -You can get it via the kernel.org site, at https://www.kernel.org/pub/software/scm/git[], or the mirror on the GitHub website, at https://github.com/git/git/releases[]. -It's generally a little clearer what the latest version is on the GitHub page, but the kernel.org page also has release signatures if you want to verify your download. +هنگامی که تمام وابستگی‌های لازم را حل کرده بودید می‌توانید ادامه داده و آخرین تاربالی که برچسب _release_ خورده را از جاهای مختلف تهیه کنید. +شما می‌توانید آنرا از سایت kernel.org به آدرس https://www.kernel.org/pub/software/scm/git[] یا از یکی از آینه‌های وبسایت گیت‌هاب در https://github.com/git/git/releases[] دریافت کنید. +به طور کل در صفحه گیت‌هاب مشخص‌تر است که آخرین نسخه چیست لکن اگر مایلید برای دانلودتان امضاهای نسخه‌های ارائه شده را بررسی کنید صفحه kernel.org آنرا هم شامل می‌شود. -Then, compile and install: +پس از این مرحله، کامپایل و نصب کنید: [source,console] ---- -$ tar -zxf git-2.0.0.tar.gz -$ cd git-2.0.0 +$ tar -zxf git-2.8.0.tar.gz +$ cd git-2.8.0 $ make configure $ ./configure --prefix=/usr $ make all doc info $ sudo make install install-doc install-html install-info ---- -After this is done, you can also get Git via Git itself for updates: +پس از اینکه تمام شد می‌توانید گیت را با خود گیت آپدیت کنید: [source,console] ---- diff --git a/book/01-introduction/sections/what-is-git.asc b/book/01-introduction/sections/what-is-git.asc new file mode 100644 index 000000000..6c7a0064a --- /dev/null +++ b/book/01-introduction/sections/what-is-git.asc @@ -0,0 +1,112 @@ +=== گیت چیست؟ + +بنابراین به طور مختصر گیت چیست؟ +این بخش مهمی برای یادگیری است، چراکه اگر بدانید گیت چیست و مقدمات اینکه چطوری کار می‌کند را درک کنید، کار کردن با گیت احتمالاً به طور چشم‌گیری برای شما آسان‌تر خواهد بود. +همانطور که گیت را می‌آموزید، سعی کنید ذهن خود را از چیزهایی که ممکن است درباره دیگه VCSها مانند CVS، ساب‌ورژن یا Perforce می‌دانید پاک نگه‌دارید -- این کار کمک می‌کند که از +پیچیدگی‌های حاصله ناخودآگاه به هنگام استفاده از این نرم‌افزار دوری بمانید. +اگرچه رابط کاربری گیت بسیار مشابه با دیگر VCSها است،‌ اما گیت دربارهٔ اطلاعات و ذخیره‌سازی آنها نگرش بسیار متفاوتی دارد و درک این تفاوت‌ها به شما کمک می‌کند تا از گیج شدن حین استفاده خودداری کنید.(((Subversion)))(((Perforce))) + +==== اسنپ‌شات‌ها، نه تفاوت‌ها + +تفاوت اصلی بین گیت و هر VCS دیگری (ساب‌ورژن و دوستان) در نحوهٔ نگرش گیت به داده‌هایش است. +از منظر مفهومی، بیشتر دیگر سیستم‌ها اطلاعات را به عنوان لیستی از تغییرات اعمال شده روی یک فایل پایه ذخیره می‌کنند. +این دسته از سیستم‌ها (CVS، ساب‌ورژن، Perforce، Bazaar، و غیره) به اطلاعاتی که ذخیره می‌کنند به عنوان مجموعه‌ای از فایل‌ها و تغییراتی که در طی زمان به آنها اعمال شده می‌نگرند +(به طور کل این رفتار کنترل نسخه _دلتا-پایه_ نامیده می‌شود). + +.ذخیره داده‌ها به عنوان تغییرات اعمال شده به روی یک نسخه پایه از هر فایل. +image::images/deltas.png[Storing data as changes to a base version of each file.] + +گیت به داده یا ذخیره‌کردن آن به این نحو نمی‌نگرد. +در عوض، گیت به داده‌هایش بیشتر به مانند یک سری از اسنپ‌شات‌هایی از یک فایل‌سیستم مینیاتوری می‌نگرد. +با گیت، هر بار که کامیت (Commit/واگذاری) -- یا وضعیت پروژه را ذخیره -- می‌کنید، گیت یک تصویر از تمام شمایل فایل‌های شما در آن لحظه می‌گیرد و یک رفرنس را به آن اسنپ‌شات در خود ذخیره می‌کند. +برای بهینه بودن، اگر فایل‌ها تغییری نکرده بودند، گیت دیگر آن فایل را ذخیره نمی‌کند و فقط یک لینک به نسخه قبلی عیناً مشابه آن فایل که قبلاً ذخیره کرده بود را جایگزین می‌کند. +گیت به داده‌هایش بیشتر به مثل *جریانی از اسنپ‌شات‌ها* می‌نگرد. + +.ذخیره داده‌ها به عنوان اسنپ‌شات‌هایی از پروژه در طول زمان. +image::images/snapshots.png[Git stores data as snapshots of the project over time.] + +این نقطه تمایز مهمی بین گیت و تقریباً تمام دیگر VCSهاست؛ +باعث این است که گیت غالب دیدگاه‌های کنترل نسخه را که بیشتر سیستم‌ها از نسل‌های قبل کپی کرده بودند را بازبینی کند. +همین اصل گیت را بیشتر یک فایل‌سیستم کوچک با ابزارهای افزودهٔ خارق‌العاده قدرتمند می‌کند تا یک VCS خشک و خالی. +در ادامه، هنگامی که برنچ‌سازی در <> توضیح داده شد، مفصل‌تر مزایای دیدن داده‌هایتان به روش گیت را بررسی خواهیم کرد. + +==== غالب عملیات‌ها محلی است + +اکثر عملیات‌ها در گیت فقط به فایل‌های محلی و منابع نیاز دارند تا کار کنند -- عموماً اطلاعاتی از کامپیوتر دیگری روی شبکهٔ شما احتیاج نیست. +اگر به یک CVCS دیگر عادت دارید که بیشتر عملیات‌ها آن تأخیر مازاد شبکه را دارند، این جنبه از گیت باعث می‌شود که فکر کنید خدایان سرعت گیت را با قدرت‌های ماورا طبیعی تجهیز کردند. +چراکه شما تمام تاریخچه پروژه را همین جا روی هارد‌دیسک خود دارید، اکثر عملیات‌ها تقریباً درجا انجام می‌شوند. + +به طور مثال، برای گشتن در تاریخچه پروژه، گیت نیازی ندارد تا سرور برود که تاریخچه را برگرداند و به شما نمایش دهد -- آنرا به سادگی از پایگاه‌داده محلی شما می‌خواند. +این بدان معناست که شما می‌توانید تاریخچه خود را تقریباً بلادرنگ مشاهده کنید. +اگر می‌خواهید که تغییرات بین این نسخه یک فایل و نسخه یک ماه پیشش را ببینید، گیت می‌تواند فایل یک ماه قبل را جستوجو کند و یک محاسبه محلی برای شما انجام دهد تا اینکه بخواهد از یک سرور دوردست بخواهد یا +اینکه نسخه‌ای قدیمی از فایل را از سرور بخواهد تا این محاسبه را به طور محلی روی آن انجام دهد. + +علاوه بر آن به این معناست که تنها تعداد کمی از کار‌ها را هنگام آفلاین بودن یا آف-VPN بودن نمی‌توانید انجام دهید. +اگر سوار هواپیما یا قطار شده‌اید و می‌خواهید کمی کار کنید، می‌توانید با سعادت کامیت کنید (البته به کپی _محلی_ خودتان، به‌یاد‌ دارید؟) تا به یک شبکه متصل شوید تا آپلود لازمه را انجام دهید. +اگر به خانه رفته‌اید و کلاینت VPN شما پاسخگو نیست، همچنان می‌توانید کار کنید. +در بسیاری از دیگر سیستم‌ها، انجام این کارها یا بسیار دردناک است یا غیرممکن. +در Perforce، به طور مثال، مادامی که به سرور متصل نیستید نمی‌توانید کار خاصی بکنید؛ در ساب‌ورژن و CVS، شما می‌توانید فایل‌ها را ویرایش کنید، اما نمی‌توانید تغییرات را به پایگاه‌داده‌تان +کامیت کنید (چون پایگاه‌داده شما آفلاین است). شاید این مشکل بزرگی به نظر نرسد، اما در عمل از تفاوت احتمالی عظیمی که ایجاد می‌کند، متعجب خواهید شد. + +==== گیت یکپارچگی دارد + +هر چیزی در گیت قبل از اینکه ذخیره شود چک‌سام می‌شود و سپس متعاقباً با آن چک‌سام فراخوانی می‌شود. +این بدان معناست که غیرممکن است که محتوای فایل یا پوشه‌ای را بدون اینکه گیت متوجه شود ویرایش کنید. +این کاکرد درون گیت و در پایین‌ترین مرتبه‌ها ساختار یافته و با تاروپود فلسفه‌اش همراه است. +ممکن نیست که شما اطلاعات را حین انتقال یا بر اثر خرابی از دست بدهید بدون اینکه گیت آنرا تشخیص دهد. + +سازوکاری که گیت برای چک‌سام کردن استفاده می‌کند هش یا درهم‌سازی SHA-1 نام دارد.(((SHA-1))) +این هش یک رشته ۴۰-حرفی ساخته شده از کاراکترهای هگزادسیمال (0-9 و a-f) است و بر اساس محتوای یک فایل یا ساختار پوشه در گیت محاسبه می‌شود. +یک هش SHA-1 چیزی شبیه به این است: + +[source] +---- +24b9da6552252987aa493b52f8696cd6d3b00373 +---- + +شما این مقادیر هش را در همه‌جا در گیت می‌بینید چرا که از آن‌ها بسیار استفاده می‌کند. +در حقیقت گیت همه‌چیز را در پایگاه‌داده‌اش، نه براساس نام فایل، بلکه بر اساس مقدار هش محتوایش ذخیره می‌کند. + +==== به طور کلی گیت فقط داده می‌افزاید + +وقتی که کاری در گیت می‌کنید، تقریباً همهٔ آن _افزودن_ به اطلاعات درون پایگاه‌داده گیت است. +به بیان دیگر، انجام کاری که سیستم نتواند آنرا بازگردانی کند یا اجبار آن به پاک‌سازی کامل اطلاعات به هر نحو بسیار دشوار است. +اما در هر VCS دیگر، شما می‌توانید تغییراتی که هنوز کامیت نکرده‌اید بهم بریزید یا از دست بدهید، اما بعد از اینکه یک اسنپ‌شات به گیت کامیت کردید، از دست دادن آن بسیار مشکل است، +بخصوص اگر به طور منظم پایگاه‌داده‌تان را به مخزنی دیگر پوش (Push/هل دادن) می‌کنید. + +این‌ها همه استفاده از گیت را به یکی از لذت‌های دنیوی تبدیل می‌کند چراکه می‌دانیم که می‌توانیم آزمون و خطای بدون خطر خراب‌کاری کردن داشته باشیم. +برای نظارهٔ عمیق اینکه چگونه گیت داده‌هایش را ذخیره می‌کند و اینکه چگونه می‌توانید اطلاعاتی که به نظر از دست‌رفته می‌آیند را بازگردانی کنید به <> مراجعه کنید. + +==== سه حالت ممکنه + +حال توجه کنید -- مسئله اصلی که باید درباره گیت بخاطر بسپارید اگر می‌خواهید که فرآیند یادگیری شما به سادگی پیش رود، اینجاست. +گیت سه حالت اصلی دارد که فایل‌های شما می‌توانند به خود بگیرند: _ویرایش‌شده_، _استیج‌شده_ و _کامیت‌شده_: + +* ویرایش‌شده (Modified) به این معناست که شما تغییری در فایل ایجاد کرده‌اید اما هنوز آنرا به پایگاه داده خود کامیت نکرده‌اید. +* استیج‌شده به این معناست که شما ویرایشی در فایل را نسخهٔ حال آن علامت‌گذاری کرده‌اید تا به اسنپ‌شاتِ کامیت بعدی شما اضافه شود. +* کامیت‌شده به این معناست که اطلاعات با امنیت کامل در پایگاه‌داده محلی شما ذخیره شده‌اند. + +پس از این به سه بخش اصلی یک پروژه گیت می‌رسیم: درخت فعال/کاری (Working Tree)، صحنه (Staging Area) و پوشه گیت. + +.درخت کاری، صحنه و پوشه گیت. +image::images/areas.png["Working tree, staging area, and Git directory."] + +درخت کاری یا درخت فعال یک چک‌اوت از یکی از نسخه‌های پروژه است. +این فایل‌ها از پایگاه‌داده فشرده درون پوشه گیت بیرون کشیده شده و روی دیسک برای استفاده یا ویرایش شما گذاشته می‌شوند. + +صحنه یا استیج یک فایل است، عموماً در پوشه گیت شماست، که اطلاعاتی درباره اینکه در کامیت بعدی چه چیزی باشد را شامل می‌شود. +نام فنی آن در ادبیات گیتی «ایندکس» است، اما عبارت «صحنه» هم به کار گرفته می‌شود. + +پوشه گیت جایی است که گیت فراداده‌ها (Metadata) و آبجکت‌های پایگاه‌داده را برای پروژه شما نگه‌داری می‌کند. +این مهمترین جز گیت است، و چیزی است که وقتی یک مخزن را از کامپیوتری دیگر _کلون_ می‌کنید کپی می‌شود. + +روند کاری پایه گیت به این شکل است: + +1. شما فایل‌هایی را در درخت کاری خود ویرایش می‌کنید. +2. به طور انتخابی آن‌هایی را که می‌خواهید در کامیت بعدیتان باشند را به صحنه می‌آورید -- استیج می‌کنید -- که باعث می‌شود _فقط_ آن تغییرات به صحنه اضافه شوند ولاغیر آن چیزی که انتخاب کردید. +3. یک کامیت می‌گیرید، که فایل‌ها را آنگونه که در صحنه بودند را به طور دائمی به اسنپ‌شاتی در پوشه گیت شما تبدیل می‌کند. + +اگر نسخه خاصی از فایلی در پوشه گیت است _کامیت‌شده_ به حساب می‌آید. +اگر ویرایش شده و به صحنه اضافه شده، _استیج‌شده_ است. +و اگر از موقعی که چک‌اوت شده تغییری در آن ایجاد شده ولکن استیج نشده، _ویرایش‌شده_ است. +در <>، بیشتر درباره این حالات و اینکه چطور می‌توان از آنها در استیج استفاده کرد یا به طور کلی آنها را دور زد را می‌آموزید. diff --git a/book/02-git-basics/1-git-basics.asc b/book/02-git-basics/1-git-basics.asc deleted file mode 100644 index e40daa59a..000000000 --- a/book/02-git-basics/1-git-basics.asc +++ /dev/null @@ -1,27 +0,0 @@ -[[_git_basics_chapter]] -== پایه های گیت - -اگر تنها یک فصل را برای آغاز کردن گیت باید خواند، آن فصل همین است. -این فصل تمام فرمان های پایه ای را که برای انجام بخش زیادی از کارهای گیت نیاز دارم پوشش می دهد. در کار با گیت زمان زیادی را باید با ین دستورات و فرمان ها گذراند. -در پایان این بخش، شما باید توانایی پیکربندی و راه اندازی یک مخرن، آغازیدن و پایان بخشیدن به دنبال کردن فایلهاو ثبت تغییرات را داشته باشید. -همچنین به شما نشان خواهیم داد که چگونه گیت برخی از فایلها و الگوهای نام فایل را نادیده می گیرد، چگونه اشتباهات را به سادگی و سرعت برگردانید، چگونه تاریخچه ای از پروژه را وارسی کنید و تغییرات بین ثبت های مختلف را با هم برابر سازی و مقایسه کنید. و همچنین چگونه از مخازن دوردست واکشی کنید و ثبت ها را به آنها اعمال کنید. - -include::sections/getting-a-repository.asc[] - -include::sections/recording-changes.asc[] - -include::sections/viewing-history.asc[] - -include::sections/undoing.asc[] - -include::sections/remotes.asc[] - -include::sections/tagging.asc[] - -include::sections/aliases.asc[] - -=== چکیده - -در این جا، شما می توانید تمام عملیات پایه ای گیت را انجام دهید - ساخت و نمونه برداری از مخزن، تغییر، و ثبت تغییرات، و دیدن تمام تغییراتی که مخزن به خود دیده است. -پس از این، ویژگی کشنده ای از گیت را به نمایش خواهیم گذاشت: ساختار شاخه سازی. - diff --git a/book/02-git-basics/sections/aliases.asc b/book/02-git-basics/sections/aliases.asc index b0b49f9cd..f66f54e3d 100644 --- a/book/02-git-basics/sections/aliases.asc +++ b/book/02-git-basics/sections/aliases.asc @@ -1,16 +1,16 @@ [[_git_aliases]] -=== نام های مستعار در گیت +=== نام‌های مستعار در گیت (((aliases))) -پیش از پایان بخش پایه های گیت، تنها یک نکته کوچک می ماند که میتواند تجربه ی کارتان را با گیت ساده تر، آسان تر و آشناتر کند: نام های مستعار. -ما دیگر به .... -We won't refer to them or assume you've used them later in the book, but you should probably know how to use them. +پیش از پایان بخش پایه‌های گیت، تنها یک نکته کوچک می ماند که میتواند تجربهٔ کارتان را با گیت ساده تر، آسان تر و آشناتر کند: +نام‌های مستعار (آلیاز/alias). +ما به نام‌های مستعار اشاره نخواهیم کرد یا تصور می‌کنیم که شمااز آنها در کتاب استفاده کرده‌ بودید اما شاید بهتر باشد بدانید +که چگونه با آنها کار کنید. +اگر شما دستوراتی را خلاصه یا بخش بخصوصی از آن را بنویسید گیت نمی‌تواند در بخش از دستورات شما را حدس بزند به همین دلیل +شما می‌توانید به راحتی با تنظیم الیازهایی بر روی دستوراتی که از آن استفاده می‌کنید دستورات را آنگونه که دوست دارید بنویسید. +با دستور `git config`. -گیت توانایی پی بردن خودکار به دستورات نیمه نوشته را ندارد. - اگر می خواهید فقط بخشی از یک دستور را تایپ کنید و گیت آن را بشناسد، به سادگی می توان یک نام مستعار با دستور -`git config`.(((git commands, config))) بسازید. - -برای ساخت نام مستعار، در اینجا چند مثال می آورید: +برای ساخت آلیاز، مانند مثل‌های زیر آنگونه می‌خواهید تنظیمات را اعمال کنید: [source,console] ---- @@ -20,18 +20,18 @@ $ git config --global alias.ci commit $ git config --global alias.st status ---- -یعنی به جای نوشتن دستور `git commit`, دستور `git ci` بسنده می کند. -همین طور که با گیت کار می کنید، شاید دستوری دیگر را بسیار تکرار کنید; با خیال آسوده نامهای مستعار بسازید. +برای مثال -- به جای وارد کردن `git commit`،‌ شما فقط نیاز دستور `git ci` را وارد کنید. +همین طور که با گیت کار می کنید، شاید دستورات دیگری را مکرران استفاده کنید;با خیالی راحت الیازی جدید بسازید. -این ریزه کاری در ساخت دستوراتی که از نظر شما باید در گیت باشد، می تواند بسیار کمک کند. -برای نمونه، برای رفع مشکل برگشت استقرار موقت یا همان unstaging کردن یک فایل، می توانید دستور ویژه خودتان را به گیت بیافزایید: +این تکنیک می‌تواند در ساخت دستورات جدید بسیار مفید باشد. +برای نمونه، برای رفع مشکل unstaging کردن یک فایل، می‌توانید دستور ویژه خودتان را به گیت بیافزایید: [source,console] ---- $ git config --global alias.unstage 'reset HEAD --' ---- -با این کار دو دستور زیر با هم برابرند و یک کار را انجام می دهند.: +با این کار دو دستور زیر با هم برابراند و یک کار را انجام می‌دهند: [source,console] ---- @@ -39,15 +39,15 @@ $ git unstage fileA $ git reset HEAD -- fileA ---- -کمی روشن تر شد. -ایجاد دستور `last` هم فراگیر است، به این شکل: +به نظر کمی قضیه قابل فهم و روشن شد. +همچنین معمولا از دستور `last` نیز به دین صورت استفاده می‌شود: [source,console] ---- $ git config --global alias.last 'log -1 HEAD' ---- -با این روش، به سادگی می توانید آخرین ثبت خود را ببینید. +با این روش، به سادگی می‌توانید آخرین کامیت را مشاهده کنید. [source,console] ---- @@ -56,18 +56,18 @@ commit 66938dae3329c7aebe598c2246a8e6af90d04646 Author: Josh Goebel Date: Tue Aug 26 19:48:51 2008 +0800 - test for current head + Test for current head Signed-off-by: Scott Chacon ---- -As you can tell,گیت به سادگی دستور جدید را با هرآنجه شما به عنوان نام مستعار می سازید جایگزین می کند. -با این وجود، شاید شما بخواهید یک دستور بیرونی را اجرا کنید نه یک دستور زیر مجموعه ی گیت. +همانطور که گیت به سادگی دستورات جدید را با هرآنجه شما به عنوان نام مستعار می سازید جایگزین می کند. +با این وجود، شاید بخواهید یک دستور خارجی را اجرا کنید که آن دستور زیر مجموعه‌ی گیت باشد. در این مورد، دستور را با علامت `!` آغاز می کنیم. -این کار زمانی سودمند است که شما ابزار خودتان را برای کار با مخازن گیت ایجاد کرده اید. +این امکان زمانی سودمند است که ابزار خودتان برای کار با مخزن گیت بنویسید. -ما می توانیم با نام مستعار، به جای دستور `gitk` ، دستور `git visual` را بکار بگیریم. به این ترتیب: +ما می‌توانیم با آلیاز، به جای دستور `gitk`، دستور `git visual` را بکار بگیریم. به این ترتیب: [source,console] diff --git a/book/02-git-basics/sections/getting-a-repository.asc b/book/02-git-basics/sections/getting-a-repository.asc index c2fd7c4f5..fc2565b14 100644 --- a/book/02-git-basics/sections/getting-a-repository.asc +++ b/book/02-git-basics/sections/getting-a-repository.asc @@ -17,7 +17,7 @@ ---- $ cd /home/user/my_project ---- -در مک: +برای مک: [source,console] ---- $ cd /Users/user/my_project @@ -25,7 +25,7 @@ $ cd /Users/user/my_project در ویندوز: [source,console] ---- -$ cd /c/user/my_project +$ cd C:/Users/user/my_project ---- و سپس در آنجا دستور زیر را بزنید: @@ -37,50 +37,59 @@ $ git init با زدن این دستور یک پوشه تاره به نام `.git` ساخته می شود که تمام فایلهایی که مخزن نیاز دارد -- اسکلت یک مخزن گیت -- را در برد دارد. تا ایجای کار، گیت تغییرات هیچ فایلی را دنبال نمی کند. -(برای اینکه بدانید در پوشه `.git` که هم اکنون ایجاد کردید، چه فایلهایی وجود دارند، <<_git_internals>> را ببینید.)(((git commands, init))) +(برای اینکه بدانید در پوشه `.git` که هم اکنون ایجاد کردید، چه فایلهایی وجود دارند، <> را ببینید.)(((git commands, init))) -If you want to start version-controlling existing files (as opposed to an empty directory), you should probably begin tracking those files and do an initial commit. -You can accomplish that with a few `git add` commands that specify the files you want to track, followed by a `git commit`: +اگر می‌خواهید شروع به کنترل نسخه فایل‌های موجود در پروژه کنید (مگر اینکه پوشه خالی باشد) شاید بهتر باشد که آنها را ترک +یا مورد پیگیری قرار دهید و اولین کامیت یا کامیت ابتدایی را انجام دهید. شما می‌توانید با وارد کردن چند دستور `git add` مشخص کنید +که چه فایل‌هایی ترک شوند و در اخر نیز آنها را با دستور `git commit` کامیت می‌کنید. [source,console] ---- $ git add *.c $ git add LICENSE -$ git commit -m 'initial project version' +$ git commit -m 'Initial project version' ---- -We'll go over what these commands do in just a minute. -At this point, you have a Git repository with tracked files and an initial commit. +کمی جلوتر خواهید فهمید که دستورات بالا دقیقاُ چه کاری انجام می‌دهند. +در حال حاضر ما یک مخزن گیت با فایل‌هایی که ترک شده‌اند و یک کامیت شروع داریم. [[_git_cloning]] -==== Cloning an Existing Repository +==== ساخت یک کلون از مخزن موجود -If you want to get a copy of an existing Git repository -- for example, a project you'd like to contribute to -- the command you need is `git clone`. -If you're familiar with other VCS systems such as Subversion, you'll notice that the command is "clone" and not "checkout". -This is an important distinction -- instead of getting just a working copy, Git receives a full copy of nearly all data that the server has. -Every version of every file for the history of the project is pulled down by default when you run `git clone`. -In fact, if your server disk gets corrupted, you can often use nearly any of the clones on any client to set the server back to the state it was in when it was cloned (you may lose some server-side hooks and such, but all the versioned data would be there -- see <<_getting_git_on_a_server>> for more details). +اگر می‌خواهید یک کپی کامل از یک مخزن از پیش موجود را داشته باشید -- برای مثال، پروژه‌ای که علاقه دارید در آن مشارکت کنید-- دستوری که به آن +احتیاج دارید `git clone` است. +اگر کمی با دیگر نرم‌افزارهای کنترل نسخه آشنا باشید مانند ساب‌ورژن، متوجه‌ خواهید شد که دستور این فعل `clone` است، +نه `checkout`،‌این یک تفاوت خیلی مهم است -- به جای اینکه یک نسخه کپی از پروژه به دست آورید، گیت به طور مستقیم یک نسخه کامل از تمامی +داده‌هایی که در سرور وجود دارد را تحویل می‌گیرد. -You clone a repository with `git clone `.(((git commands, clone))) -For example, if you want to clone the Git linkable library called `libgit2`, you can do so like this: +به صورت پیش‌فرض با اجرای دستور `git clone` هر نسخه‌ای از هر فایلی در تاریخچهٔ پروژه توسط گیت آورده می‌شود. +در حقیقت اگر احیاناً دیسک سرور شما دچار مشکل گردد و اطلاعات از دست روند اکثرا شما این می‌توانید به طور مستقیم از هر کلون دیگری +روی هر کلاینت دیگری استفاده کنید تا اطلاعات سرور را به همان حالتی که به هنگام کلون کردن بود بازگردد. (ممکن است بعضی از هوک‌های سرور و این قبیل اطلاعات از دست بروند اما تمام نسخه‌های کنترل شده خواهند ماند +-- برای جزئیات بیشتر <> را مطالعه کنید.) + +با دستور (((git commands, clone))) `git clone (url)` یک مخزن را کلون می‌کنید. +برای مثال، اگر بخواهید یک کتاب‌خانه گیت قابل لینک به نام `libgit2` را کلون کنید، می‌توانید با این روش انجام دهید: [source,console] ---- $ git clone https://github.com/libgit2/libgit2 ---- -That creates a directory named `libgit2`, initializes a `.git` directory inside it, pulls down all the data for that repository, and checks out a working copy of the latest version. -If you go into the new `libgit2` directory that was just created, you'll see the project files in there, ready to be worked on or used. +با اجرای خط بالا در مرحله‌ی اول یک پوشه به نام `libgit2` ساخته می‌شود، در پوشه `libgit2` یک پوشه جدید به نام `.git` ساخته +و مخزن گیت راه‌اندازی ‌می‌شود، تمام اطلاعات از مخزن اصلی دریافت می‌شوند و ما را به اخرین نسخه از پروژه چک‌اوت می‌کند. +اگر وارد پوشه جدید `libgit2` شوید، ‌خواهید دید که فایل‌های پروژه حاضر و آماده استفاده هستند. -If you want to clone the repository into a directory named something other than `libgit2`, you can specify that as the next command-line option: +اگر بخواهید مخزن مورد نظر را در پوشه‌ای با نام دلخواه خودتون بجای libgit2 کلون کنید، می‌توانید نام پوشه دلخواه را مانند دستور پایین به عنوان آرگومان اضافه مشخص کنید. [source,console] ---- $ git clone https://github.com/libgit2/libgit2 mylibgit ---- -That command does the same thing as the previous one, but the target directory is called `mylibgit`. +دستور بالا مراحل قبل را انجام می‌دهد با این تفاوت که نام پوشه‌ای که ساخته می‌شود `mylibgit` خواهد بود. -Git has a number of different transfer protocols you can use. -The previous example uses the `https://` protocol, but you may also see `git://` or `user@server:path/to/repo.git`, which uses the SSH transfer protocol. -<<_getting_git_on_a_server>> will introduce all of the available options the server can set up to access your Git repository and the pros and cons of each. +گیت دارای تعداد زیادی پروتکل‌های انتقال است که شما می‌توانید از آن‌ها استفاده کنید. +در مثال قبل از پروتکل `//:https` استفاده شد، اما شاید شما `//:git` یا `user@server:path/to/repo.git` نیز دیده باشید، +که از پروتکل SSH استفاده می‌کند. +در <> تمام گزینه‌های موجود برای را دسترسی به مخزن گیت را معرفی خواهد کرد و درباره مضرات و فواید هر کدام +توضیح خواهد داد. diff --git a/book/02-git-basics/sections/recording-changes.asc b/book/02-git-basics/sections/recording-changes.asc index 52e290ee9..9ce3f1a14 100644 --- a/book/02-git-basics/sections/recording-changes.asc +++ b/book/02-git-basics/sections/recording-changes.asc @@ -1,26 +1,27 @@ -=== Recording Changes to the Repository +=== ثبت تغییرات یک مخزن +در این بخش، شما باید یک مخزن واقعی گیت بر روی سیستم لوکال داشته باشید و یک چک‌اوت یا ـ‌کپی کاری‌ـ تمام فایل‌های موجود مقابل شما باشد. +معمولا شما می‌خواهید شروع به تغییر دادن کنید و اسنپ‌شات‌ها را در مخزن کامیت کنید، +هر بار که پروژه به وضعتی رسید که شما می‌خواهید آن را ثبت کنید. -At this point, you should have a _bona fide_ Git repository on your local machine, and a checkout or _working copy_ of all of its files in front of you. -Typically, you'll want to start making changes and committing snapshots of those changes into your repository each time the project reaches a state you want to record. +یادتون باشه که هر فایلی در پوشه کاری شما به طور کلی دو وضعیت دارد: _tracked(دنبال شده/ترکت)ـ یا _untracked(دنبال نشده/آن‌ترکت). +ترکت فایلی هستید که در اخرین اسنپ‌شات شما بوده‌اند؛ آن‌ها می‌توانند وضعتی مثل ـ‌unmodified(تغییر نکرده/آن‌مودیفاید)ـ، +ـmodified(تغییر کرده/مودی‌فاید)ـ، یا _staged(ظاهر شده/استیجد)_ داشته باشند. +به طور خلاصه، ترکت فایل‌ها آنهایی هستند که گیت آن‌ها را می‌شناسد. -Remember that each file in your working directory can be in one of two states: _tracked_ or _untracked_. -Tracked files are files that were in the last snapshot; they can be unmodified, modified, or staged. -In short, tracked files are files that Git knows about. +آن‌ترکت فایل‌ها بقیه هستند -- هر فایلی در اسنپ‌شات آخر شما نبوده باشد و شما را آن را ـadd(همان عمل استیج است/اَد)ـ نکرده باشید. +وقتی اول مخزنی را کلون می‌کنید، همه‌ی فایل‌ها ترکت شده و آن‌مودیفاید هستند زیرا گیت قبلا بررسی کرده است و هنوز شما تغییراتی را +اعمال نکرده‌اید. +به محض تغییر فایل‌ها، گیت وضعیت‌ آن‌ها را به مودیفاید تغییر می‌دهد، چون شما آن را نسبت به کامیت آخر تغییر داده‌اید. +همانطور که کار می‌کنید، شما فایل‌های مودیفاید شده را انتخاب و اَد می‌کنید و سپس همه‌ی آن را کامیت می‌کنید، و این چرخه ادامه دارد. -Untracked files are everything else -- any files in your working directory that were not in your last snapshot and are not in your staging area. -When you first clone a repository, all of your files will be tracked and unmodified because Git just checked them out and you haven't edited anything. -As you edit files, Git sees them as modified, because you've changed them since your last commit. -As you work, you selectively stage these modified files and then commit all those staged changes, and the cycle repeats. - -.The lifecycle of the status of your files. -image::images/lifecycle.png[The lifecycle of the status of your files.] +چرخه عمر وضعیت فایل‌های شما +image::images/lifecycle.png[چرخه عمر وضعیت یک فایل] [[_checking_status]] -==== Checking the Status of Your Files - -The main tool you use to determine which files are in which state is the `git status` command.(((git commands, status))) -If you run this command directly after a clone, you should see something like this: +==== بررسی وضعیت فایل‌ها +ابزار اصلی‌ای که شما برای تعیین وضعیت فایل‌ها استفاده می‌کنید، دستور `git status` است. (((git commands, status))) +اگر شما دستور را مستقیماً بعد از کلون اجرا کنید،‌ چیزی شبیه به این خواهی دید: [source,console] ---- @@ -29,15 +30,14 @@ On branch master Your branch is up-to-date with 'origin/master'. nothing to commit, working directory clean ---- +این بدین معنی است که پوشه کاری شما تمیز است -- به زبان دیگر، هیچ کدام از فایل‌های ترکت شده تغییر داده نشده یا وضعیت مودیفاید ندارند. +همچنین گیت هیچ فایل دنبال نشده یا آن‌ترکت را نمی‌بینید. +در آخر، این دستور به شما می‌گوید که بر روی کدام برنچ هستید و شما از اختلافات بین برنچ شما و برنچ روی سرور مطلع می‌سازد. +فعلا، آن برنچ همیشه ``master`` است که به صورت پیش فرض ساخته شده؛ نگران نباشید در بخشی <<_git_branching>> درباره این موضوع +با جزئیات بحث خواهد شد. +بیایید یه فایل جدید به پروژه اضافه کنیم، یک فایل `README` ساده. +اگر از قبل وجود نداشته باشد، می‌توانید با اجرای دستور `git status` ببنید که فایل به وضعیت آن‌ترکت درآمده است: -This means you have a clean working directory -- in other words, none of your tracked files are modified. -Git also doesn't see any untracked files, or they would be listed here. -Finally, the command tells you which branch you're on and informs you that it has not diverged from the same branch on the server. -For now, that branch is always ``master'', which is the default; you won't worry about it here. -<<_git_branching>> will go over branches and references in detail. - -Let's say you add a new file to your project, a simple `README` file. -If the file didn't exist before, and you run `git status`, you see your untracked file like so: [source,console] ---- @@ -52,24 +52,25 @@ Untracked files: nothing added to commit but untracked files present (use "git add" to track) ---- +می‌توانید فایل `README` جدید که ساختید را در حالت آن‌ترکت ببینید، چون خروجی وضعیت فایل در زیر تیتر ``Untracked files`` است. +آن‌ترکت به طوری کلی به این معنی است که گیت آن را در آخرین اسنپ‌شات(کامیت) ندیده است. +گیت به هیچ عنوان آن را در اسنپ‌شات‌های(کامیت‌ها) بعدی ثبت نمی‌کند تا زمانی که شما آن را اَد کنید و به روی استیج بیارید و کامیت کنید. +پس گیت به این صورت کار میکنه در نتیجه شما‌ نمی‌توانید به صورت تصادفی شروع به اضافه کردن فایلی دودویی در یک فایل دیگر کنید که +منظورتان آن فایل نبوده است. +خب شما می‌خواهید شروع به اضافه کردن فایل `README` کنید، پس بیایید به گیت این موضوع را اعلام کنیم و آن را به حالت `tracked` +در بیاوریم. -You can see that your new `README` file is untracked, because it's under the ``Untracked files'' heading in your status output. -Untracked basically means that Git sees a file you didn't have in the previous snapshot (commit); Git won't start including it in your commit snapshots until you explicitly tell it to do so. -It does this so you don't accidentally begin including generated binary files or other files that you did not mean to include. -You do want to start including `README`, so let's start tracking the file. - -[[_tracking_files]] -==== Tracking New Files - -In order to begin tracking a new file, you use the command `git add`.(((git commands, add))) -To begin tracking the `README` file, you can run this: +[[_tracking_files]]‍ +==== دنبال کردن یک فایل جدید +به این ترتیب برای قرار دادن یک فایل در حالت tracked و اینکه گیت بتواند آن را در اسنپ‌شات‌ها بعدی را شامل کند باید از دستور +`git add` استفاده کنید.(((git commands, add))) +برای اضافه کردن فایل `README`، باید دستور زیر را وارد کنید: [source,console] ---- $ git add README ---- - -If you run your status command again, you can see that your `README` file is now tracked and staged to be committed: +اگر دستور `git status` را وارد کنید، می‌توانید ببیند فایل `README` حالا در حال ترکت و استیج شده و فعل کامیت است: [source,console] ---- @@ -77,21 +78,22 @@ $ git status On branch master Your branch is up-to-date with 'origin/master'. Changes to be committed: - (use "git reset HEAD ..." to unstage) + (use "git restore --staged ..." to unstage) new file: README ---- -You can tell that it's staged because it's under the ``Changes to be committed'' heading. -If you commit at this point, the version of the file at the time you ran `git add` is what will be in the historical snapshot. -You may recall that when you ran `git init` earlier, you then ran `git add ` -- that was to begin tracking files in your directory.(((git commands, init)))(((git commands, add))) -The `git add` command takes a path name for either a file or a directory; if it's a directory, the command adds all the files in that directory recursively. +به این وضعیت، اصطلاحا استیج می‌گویند چون فایل در زیر تیتر ``Changes to be committed`` و منتظر انجام فعل کامیت است. +شما احتمالا زمانی که دستور `git init` را اجرا کرده بودید نیز یکبار دستور `git add {files}` را نیز اجرا کرده باشید-- آن دستور +برای مورد دنبال قرار گرفتن فایل‌ها در درون پوشه بود.(((git commands, init)))(((git commands, add))) +دستور `git add` یا نام یک فایل را اضافه می‌کند یا نام یک پوشه را؛ اگر یک پوشه باشد، دستور به صورت بازگشتی تمامی فایل‌های و زیرپوشه‌ها +را اضافه می‌کند. -==== Staging Modified Files - -Let's change a file that was already tracked. -If you change a previously tracked file called `CONTRIBUTING.md` and then run your `git status` command again, you get something that looks like this: +==== اضافه کردن فایل‌های تغییر یافته +حالا بیایید فایلی که در حال حاضر ترکت شده را تغییر دهیم. +اگر فایل قبلی که اضافه کردیم به نام `CONTRIBUTING.md` تغییر دهیم و دوباره دستور `git status` را اجرا کنیم، +چیزی شبیه به نتیجه زیر را می‌بینید: [source,console] ---- @@ -111,11 +113,11 @@ Changes not staged for commit: ---- -The `CONTRIBUTING.md` file appears under a section named ``Changes not staged for commit'' -- which means that a file that is tracked has been modified in the working directory but not yet staged. -To stage it, you run the `git add` command. -`git add` is a multipurpose command -- you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved. -It may be helpful to think of it more as ``add precisely this content to the next commit'' rather than ``add this file to the project''.(((git commands, add))) -Let's run `git add` now to stage the `CONTRIBUTING.md` file, and then run `git status` again: +فایل `CONTROBUTING.md` در زیر بخشی به نام ``Changes not staged for commit`` ظاهر خواهد شد -- به معنی است که یک فایلی +دچار تغییر شده بود حالا ترکت شده اما هنوز آن را استیجد نکرده‌ایم، برای انجام استیج می‌بایست دستور `git add` را اجرا کنیم. +دستور `git add` چند منظوره است -- برای ترک کردن فایل‌های جدید، برای استیج کردن فایل‌های تغییر یافته و برای انجام دیگر کارها +مثل مشخص کردن مرج-کانفلیکت‌ فایل‌ها به عنوان کاری که انجام شده. +بیایید دستور `git add` را اجرا کنیم تا فایل `CONTRIBUTING.md` را استیج کنیم، و بعد دستور `git status` را دوباره وارد کنیم. [source,console] ---- @@ -131,10 +133,10 @@ Changes to be committed: ---- -Both files are staged and will go into your next commit. -At this point, suppose you remember one little change that you want to make in `CONTRIBUTING.md` before you commit it. -You open it again and make that change, and you're ready to commit. -However, let's run `git status` one more time: +هر دو فایل استیج شده‌اند و به کامیت بعدی شما اضافه خواهند شد. +در این لحظه، فرض کنید که یادتان می‌یاد یک تغییر کوچک دیگر در فایل `CONTRIBUTING.md` می‌خواهید انجام دهید، قبل از اینکه کامیت کنید. +فایل را دوباهر باز می‌کنید و تغییرات را اعمال می‌کنید، حالا اماده کامیت است. +حالا، بیایید دوباره دستور `git status` را اجرا کنیم: [source,console] ---- @@ -156,12 +158,13 @@ Changes not staged for commit: ---- -What the heck? -Now `CONTRIBUTING.md` is listed as both staged _and_ unstaged. -How is that possible? -It turns out that Git stages a file exactly as it is when you run the `git add` command. -If you commit now, the version of `CONTRIBUTING.md` as it was when you last ran the `git add` command is how it will go into the commit, not the version of the file as it looks in your working directory when you run `git commit`. -If you modify a file after you run `git add`, you have to run `git add` again to stage the latest version of the file: +چطور ممکنه؟!!! +فایل `CONTRIBUTING.md` هم به عنوان فایلی استیج شده و ـ‌همچنین‌ـ استیج نشده لیست شده است. +چطور امکان دارد؟ +خب این موضوع بر‌میگردد به گیت، وقتی دستور `git add` را اجرا می‌کنید و فایلی را استیج می‌کنید، گیت دقیقا همان تغییرات آماده کامیت می‌کند +و شما اگر واقعا کامیت کنید، نسخه‌ای جدید از فایل پروژه ایجاد خواهد شد و وقتی که قبل از کامیت دوباره تغییر بدید درحالی که آن را یکبار +استیج کرده‌اید؛ گیت تغییرات جدیدی را ثبت می‌کند و به شما می‌گوید تغییرات جدید را در کامیت جاری اعمال نمی‌کند مگر اینکه دوباره آن را +استیج کنید. [source,console] ---- @@ -176,11 +179,11 @@ Changes to be committed: modified: CONTRIBUTING.md ---- -==== Short Status +==== وضعیت‌های کوتاه -While the `git status` output is pretty comprehensive, it's also quite wordy. -Git also has a short status flag so you can see your changes in a more compact way. -If you run `git status -s` or `git status --short` you get a far more simplified output from the command: +خروجی `git status` خیلی توصیفی و لغوی است؛ در حالی که گیت دارای یه سری اعلام‌ وضعیت‌های کوتاه نیز می‌باشد، که می‌توانید وضعیت تغییرات +را خیلی کوتاه و خلاصه‌تر ببینید. +اگر دستور `git status -s` یا `git status --short` را وارد کنید، یک خروجی بسیار ساده شده به شما خواهد داد: [source,console] ---- @@ -192,18 +195,21 @@ M lib/simplegit.rb ?? LICENSE.txt ---- -New files that aren't tracked have a `??` next to them, new files that have been added to the staging area have an `A`, modified files have an `M` and so on. -There are two columns to the output - the left-hand column indicates the status of the staging area and the right-hand column indicates the status of the working tree. -So for example in that output, the `README` file is modified in the working directory but not yet staged, while the `lib/simplegit.rb` file is modified and staged. -The `Rakefile` was modified, staged and then modified again, so there are changes to it that are both staged and unstaged. +فایل‌های جدیدی که هنوز ترکت نشده‌اند علامت `??` مقابل آنان است، فایل‌های جدیدی که استیج شده‌اند علامت `A` دارند، +فایل‌های تغییر یافته علامت `M` دارند و بقیه نیز به همین ترتیب. +خروجی حروفی که می‌بینید عملا دو ستون است، ستون سمت چپ نشان‌دهنده وضعیت استیج است و ستون سمت راست نشان‌دهنده وضعیت درخت کاری است. +برای مثال-- در خروجی بالا، فایل `README` در پوشه کاری تغییر یافته است اما هنوز آن را استیج نکرده‌اند، +در حالی که فایل `lib/simplegit.rb` تغییر یافته و استیج شده است. +فایل `Rakefile` تغییر یافته و استیج شده بود و بعد دوباره به حالت تغییر یافته درآمده، به همین دلیل هر دو ستون آن پر است و `MM` یعنی +استیج شده و استیج نشده. [[_ignoring]] -==== Ignoring Files +==== نادیده گرفتن فایل‌ها -Often, you'll have a class of files that you don't want Git to automatically add or even show you as being untracked. -These are generally automatically generated files such as log files or files produced by your build system. -In such cases, you can create a file listing patterns to match them named `.gitignore`.(((ignoring files))) -Here is an example `.gitignore` file: +گاهی مجموعه‌ای از فایل‌ها هستند که ما نمی‌خواهیم گیت به صورت خودکار آن `add` یا آن‌ها را دنبال کند. +به صورت کلی فایل‌هایی وجود دارد که به صورت اتوماتیک ساخته می‌شود مثل لاگ فایل‌ها و... +در این گونه موارد، می‌توانید لیستی از نام فایل‌ها بسازید و آن‌ها در فایلی به نام `gitingore.` قرار بدید؛ +در اینجا مثالی برای فایل `gitignore.` داریم: [source,console] ---- @@ -212,24 +218,28 @@ $ cat .gitignore *~ ---- -The first line tells Git to ignore any files ending in ``.o'' or ``.a'' -- object and archive files that may be the product of building your code. -The second line tells Git to ignore all files whose names end with a tilde (`~`), which is used by many text editors such as Emacs to mark temporary files. -You may also include a log, tmp, or pid directory; automatically generated documentation; and so on. -Setting up a `.gitignore` file for your new repository before you get going is generally a good idea so you don't accidentally commit files that you really don't want in your Git repository. +خط اول به گیت می‌گوید که هر فایلی که با ``o.`` یا ``a.`` تمام ‌می‌شود را نادیده بگیرد. +خط دوم به گیت می‌گوید که همه‌ی فایل‌های که نام‌شان با علامت تیلد(`~`) است ناده بگیرد، از این علامت اکثر ویرایشگران متن مثل +ایمکس استفاده می‌کنند تا فایل‌های موقت خود را ذخیره کنند. +شاید شما پوشه‌های tmp, log , pid را هم اضافه کنید؛ یاد گرفتن کار با فایل `gitignore.` ضروری است، چرا باید فایلی را کامیت کنید +که نمی‌خواهید واقعا در مخزن شما وجود داشته باشد. -The rules for the patterns you can put in the `.gitignore` file are as follows: +قوانین و الگو‌هایی که می‌توانید در فایل `gitignore.` قرار بدید تا فایل مورد نظر شما در کامیت‌های بعدی حضور نداشته باشد. -* Blank lines or lines starting with `#` are ignored. -* Standard glob patterns work, and will be applied recursively throughout the entire working tree. -* You can start patterns with a forward slash (`/`) to avoid recursivity. -* You can end patterns with a forward slash (`/`) to specify a directory. -* You can negate a pattern by starting it with an exclamation point (`!`). +* خط‌هایی که با `#` شروع شوند نادیده گرفته می‌شوند. +* الگو‌‌های استاندارد کار می‌کنند و به صورت بازگشتی بر روی درخت کاری شما تاثیر می‌گذارند. +* می‌توانید الگو‌ها را با علامت اسلش رو به جلو (`/`) از حالت بازگشتی خارج کنید. +* می‌توانید از اسلش رو به جلو (`/`) پوشه‌ای مشخص را تعیین کنید. +* می‌توانید با اضافه کردن علامت تعجب (`!`) منظور جمله را برعکس کنید. -Glob patterns are like simplified regular expressions that shells use. -An asterisk (`*`) matches zero or more characters; `[abc]` matches any character inside the brackets (in this case a, b, or c); a question mark (`?`) matches a single character; and brackets enclosing characters separated by a hyphen (`[0-9]`) matches any character between them (in this case 0 through 9). -You can also use two asterisks to match nested directories; `a/**/z` would match `a/z`, `a/b/z`, `a/b/c/z`, and so on. +الگو‌های استاندارد که می‌توان استفاده که به سادگی با کد‌‌های Regex(Regural expretions) نوشته می‌شود که شل هم استفاده می‌کند. +علامت ستاره (`*`) یک یا چند کارکتر را پیدا می‌کند؛ `[abc]` هر حرفی که داخل براکت(`[]`) باشد را پیدا می‌کند( در این مورد + a, b ,c هستند). علامت سوال (`?`) یک کارکتر را پیدا می‌کند و علامت براکت به همراه دو کارکتر که با `-` از هم جدا شده باشند، + آنهایی که در آن مجموعه وجود داشته باشند را پیدا می‌کند(`[9-0]` در این مورد هر عددی که بین ۰ تا ۹ باشد). +و همچنین می‌توانید از دو ستاره `**` برای پیدا کردن پوشه‌های تو در تو استفاده کنید به این صورت `a/**/z` که نتیجه‌ی آن می‌تواند +`a/z`, `a/b/z`, `a/b/c/z`, و به همین ترتیب باشد. -Here is another example `.gitignore` file: +در این مثال دیگری برای فایل `gitignore.`داریم: [source] ---- @@ -242,7 +252,7 @@ Here is another example `.gitignore` file: # only ignore the TODO file in the current directory, not subdir/TODO /TODO -# ignore all files in the build/ directory +# ignore all files in any directory named build build/ # ignore doc/notes.txt, but not doc/server/arch.txt @@ -254,29 +264,34 @@ doc/**/*.pdf [TIP] ==== -GitHub maintains a fairly comprehensive list of good `.gitignore` file examples for dozens of projects and languages at https://github.com/github/gitignore[] if you want a starting point for your project. +در صفحه گیت‌هاب لیست قابل ملاحظه‌ای برای فایل `gitignore.` فراهم شده است که مملوع از مثال‌های مختلف برای زبان‌ها و شرایط مختلف است. +https://github.com/github/gitignore[] ==== [NOTE] ==== -In the simple case, a repository might have a single `.gitignore` file in its root directory, which applies recursively to the entire repository. -However, it is also possible to have additional `.gitignore` files in subdirectories. -The rules in these nested `.gitignore` files apply only to the files under the directory where they are located. -(The Linux kernel source repository has 206 `.gitignore` files.) - -It is beyond the scope of this book to get into the details of multiple `.gitignore` files; see `man gitignore` for the details. +در یک مورد ساده، یک مخزن شاید یک فایل `gitignore.` در پوشه اصلی داشته باشد، که به صورت بازگشتی تمام موجودیت‌های پروژه را شامل می‌شود. +با این حال، این امکان وجود دارد که در زیر پوشه‌های خود باز هم فایل `gitignore.` داشته باشد. +قوانین و الگوها در این فایل‌های `gitignore.` تو در تو فقط موجودیت‌های زیرپوشه‌‌های خود را نادیده می‌گیرند. +(مخزن اصلی سورس هسته لیوکس در فایل `gitignore.` خود ۲۰۶ فایل را نادیده می‌گیرد.) +این موضوع فراتر از بخش این کتاب است که درباره جزئیات چندین فایل `gitignore.` بگوییم. +اگر به دنبال جزئیات بیشتری هستید دستور `man gitignore` را در ترمینال وارد کنید. ==== [[_git_diff_staged]] -==== Viewing Your Staged and Unstaged Changes +==== نمایش وضعیت استیج شده‌ها و تغییرات استیج نشده -If the `git status` command is too vague for you -- you want to know exactly what you changed, not just which files were changed -- you can use the `git diff` command.(((git commands, diff))) -We'll cover `git diff` in more detail later, but you'll probably use it most often to answer these two questions: What have you changed but not yet staged? -And what have you staged that you are about to commit? -Although `git status` answers those questions very generally by listing the file names, `git diff` shows you the exact lines added and removed -- the patch, as it were. +اگر دستور `git status` کمی برایتان مبهم است -- میخواهید بفهمید دقیقا چه چیزی را تغییر داده‌اید!، نه فقط چه فایل‌هایی تغییر کرده است +(منظور جزئیات بیشتر در تغییرات اعمال شده است) -- می‌توانید از دستور `git diff` استفاده کنید.(((git commands, diff))) +درباره دستور `git diff` و جزئیات آن بعد می‌گوییم، اما احتما شما از این دستور برای پاسخ به دو سوال استفاده کنید: -Let's say you edit and stage the `README` file again and then edit the `CONTRIBUTING.md` file without staging it. -If you run your `git status` command, you once again see something like this: +چه چیزی تغییر کرده است که هنوز استیج نشده است؟ +و چه چیزی را استیج کرده‌اید و منتظر کامیت شدن است؟ +با اینکه دستور `git status` جواب آن سوالات را به صورت خیلی کلی به وسطه لیست کردن نام‌های فایل‌ها خواهد داد، اما `git diff` +جزئیات کار را با دقت تغییر در هر خط نشان می‌دهد که چه خطی اضافه یا حذف شده است. + +فرض کنیم که شما فایل `README` را تغییر داده‌اید و دوباره استیج کرده‌اید و سپس فایل `CONTRIBUTING.md` را تغییر داده و استیج نکرده‌اید. +اگر دستور ‍`git status` را اجرا کنید، به یکباره چیزی شبیه به خروجی پایین را می‌بینید: [source,console] ---- @@ -294,8 +309,7 @@ Changes not staged for commit: modified: CONTRIBUTING.md ---- - -To see what you've changed but not yet staged, type `git diff` with no other arguments: +برای دیدن تغییراتی که انجام دادید ولی هنوز استیج نکرده ایده، دستور `git diff` را بدون هیچ آرگومان دیگری وارد کنید: [source,console] ---- @@ -316,11 +330,11 @@ index 8ebb991..643e24f 100644 that highlights your work in progress (and note in the PR title that it's ---- -That command compares what is in your working directory with what is in your staging area. -The result tells you the changes you've made that you haven't yet staged. +آن دستور چیز‌هایی که در پوشه کاری شما هست با چیز‌هایی که در موقعیت استیج هست را مقایسه می‌کند. +نتیجه‌ به شما می‌گوید تغییراتی که به وجود آورده‌اید هنوز استیج نشده‌اند. -If you want to see what you've staged that will go into your next commit, you can use `git diff --staged`. -This command compares your staged changes to your last commit: +اگر شما بخواهید ببینید چه چیزی را استیج کرده‌اید که در کامیت بعدی شما باشد، با اجرا دستور `git diff --staged` نمایش را ببینید. +این دستور آخرین کامیت را با تغییرات استیج مقایسه می‌کند: [source,console] ---- @@ -334,11 +348,13 @@ index 0000000..03902a1 +My Project ---- -It's important to note that `git diff` by itself doesn't show all changes made since your last commit -- only changes that are still unstaged. -If you've staged all of your changes, `git diff` will give you no output. +خیلی مهم است که دقت کنید که `git diff` خودش به تنهایی تمام تغییر ایجاد شده را از آخرین تغییرات نشان نمی‌دهد. -- +فقط تغییراتی که هنوز استیج نشده‌اند. +اگر شما تغییراتی را به استیج کنید، `git diff` خروجی‌ای به شما نمی‌دهد. -For another example, if you stage the `CONTRIBUTING.md` file and then edit it, you can use `git diff` to see the changes in the file that are staged and the changes that are unstaged. -If our environment looks like this: +برای مثالی دیگر، اگر شما فایل `CONTRIBUTING.md` را استیج کنید و سپس آن را تغییر دهید، می‌توانید از دستور `git diff` استفاده کنید +و تغییرات ایجاد شده درون فایل که استیج شده‌اند و تغییراتی که استیج نشده‌اند. +اگر محیط ما شبیه پایین باشد: [source,console] ---- @@ -359,7 +375,7 @@ Changes not staged for commit: modified: CONTRIBUTING.md ---- -Now you can use `git diff` to see what is still unstaged: +حال می‌توانید از دستور `git diff` برای دیدن فایل‌هایی که هنوز استیج نشده‌اند استفاده کنید: [source,console] ---- @@ -375,7 +391,7 @@ index 643e24f..87f08c8 100644 +# test line ---- -and `git diff --cached` to see what you've staged so far (`--staged` and `--cached` are synonyms): +و دستور `git diff --cached` برای دیدن اینکه چه چیزی را اخیرا استیج کرده‌اید (`staged--` و `cached--` مترادف هستند.) [source,console] ---- @@ -397,21 +413,27 @@ index 8ebb991..643e24f 100644 ---- [NOTE] -.Git Diff in an External Tool +دستور `git diff` یک ابزار خارجی است. ==== -We will continue to use the `git diff` command in various ways throughout the rest of the book. -There is another way to look at these diffs if you prefer a graphical or external diff viewing program instead. -If you run `git difftool` instead of `git diff`, you can view any of these diffs in software like emerge, vimdiff and many more (including commercial products). -Run `git difftool --tool-help` to see what is available on your system. +ما در آینده از دستور `git diff` در سراسر این کتاب با موضوعات گوناگونی استفاده خواهیم کرد. +راه دیگری وجود دارد که این چنین تغییرات را ببینید یا شاد ترجیح می‌هید که از ابزارهای گرافیکی یا از ابزارهای خارجی نمایش پیشرفت کار +استفاده کنید. +اگر شما دستور `git difftool` را به جای دستور `git diff` اجرا کنید،‌ می‌توانید هرگونه از این تغییرات را در نرم‌افزاری مثل +emerge, vimdiff یا هر مورد دیگری ببینید(به علاوه محصولات تجاری دیگر). +دستور `git difftool --tool-help` را اجرا کنید تا ببنید که چه نرم‌افزار بر روی سیستم شما موجود است. ==== [[_committing_changes]] -==== Committing Your Changes +==== کامیت کردن تغییرات + +دقت کنید که موقعیت استیج شما آنطور که می‌خواستید آماده شده است، حالا شما می‌توانید تغییرات را کامیت کنید. +به یاد داشته باشید که هر چیزی که همچنان آن‌استیج هستند -- هر فایلی که شما ساختید یا تغییر داده‌اید که هنوز دستور +`git add` برای استیج کردن آن‌ها اجرا نکرده‌اید. -- به مرحله کامیت اضافه نخواهند شد. +آن‌‌ها با عنوان فایل تغییر یافته بر روی دیسک شما باقی خواهد ماند. +در این مورد، فرض کنیم که آخرین باری که دستور `git status` اجرا کردید، همه تغییرات استیج شده بودند، +پس حالا آماده‌اید که تغییرات استیج شده را کامیت کنید.(((git commands, status))) +راحت‌ترین راهی که می‌توانید کامیت را انجام دهید نوشتن دستور `git commit` است:(((git commands, commit))) -Now that your staging area is set up the way you want it, you can commit your changes. -Remember that anything that is still unstaged -- any files you have created or modified that you haven't run `git add` on since you edited them -- won't go into this commit. -They will stay as modified files on your disk. -In this case, let's say that the last time you ran `git status`, you saw that everything was staged, so you're ready to commit your changes.(((git commands, status))) The simplest way to commit is to type `git commit`:(((git commands, commit))) [source,console] @@ -419,10 +441,12 @@ The simplest way to commit is to type `git commit`:(((git commands, commit))) $ git commit ---- -Doing so launches your editor of choice. -(This is set by your shell's `EDITOR` environment variable -- usually vim or emacs, although you can configure it with whatever you want using the `git config --global core.editor` command as you saw in <<_getting_started>>).(((editor, changing default)))(((git commands, config))) +دستور بالا ادیتو متنی را باز می‌کند. +(این ادیتور متن به واسه مقداری در متغییر `EDITOR` برای محیط شل خود نوشته‌اید اجرا می‌شود -- معمولا vim یا emacs, +با این حال شما می‌تواند آن را با هر ادیتور که می‌خواهید پیکربندی کنید. با وارد کردن دستور `git config --global core.editor` +همانطور که در بخش <<_getting_started>> دیدید.)(((editor, changing default)))(((git commands, config))) -The editor displays the following text (this example is a Vim screen): +ادیتور متن زیر را تغییر می‌دهد (این مثال با ادیتور ویم است.) [source] ---- @@ -441,36 +465,41 @@ The editor displays the following text (this example is a Vim screen): ~ ".git/COMMIT_EDITMSG" 9L, 283C ---- +می‌توانید ببینید که پیام کامیت پیش فرض شامل آخرین خروجی دستور `git status` است و یک خط خالی در بالای آن. +شما می‌توانید تمام این پیام‌ها را حذف کنید و پیام خودتان را بنویسید، یا می‌توانید همانطور رها کنید تا بعدا +به شما کمک کند تا دقیقا چیزی که کامیت کرده بودید را به یاد آورید. +برای بیشتر واضح بود یادآور چیزی که تغییر دادید، می‌توانید از آپشن `v-` برای دستور `git commit` استفاده کنید. +این کار همچنین تفاوت تغییرات داخل ادیتور را قرار می‌دهد، پس می‌توانید ببینید دقیقا چه تغییراتی را کامیت می‌کنید. +وقتی از ادیتور خارج می‌شوید، گیت کامیت مورد نظر شما را با پیام کامیتی که نوشته‌اید می‌سازد(همراه توضیحات و تفاوت‌‌ها به صورت خطی) -You can see that the default commit message contains the latest output of the `git status` command commented out and one empty line on top. -You can remove these comments and type your commit message, or you can leave them there to help you remember what you're committing. -(For an even more explicit reminder of what you've modified, you can pass the `-v` option to `git commit`. -Doing so also puts the diff of your change in the editor so you can see exactly what changes you're committing.) -When you exit the editor, Git creates your commit with that commit message (with the comments and diff stripped out). - -Alternatively, you can type your commit message inline with the `commit` command by specifying it after a `-m` flag, like this: +از سویی دیگر، شما می‌توانید پیام کامیت خود را به صورت یک همراه با دستور `git commit` با آپشن `m-` بنویسید،‌ مانند مثال زیر: [source,console] ---- -$ git commit -m "Story 182: Fix benchmarks for speed" -[master 463dc4f] Story 182: Fix benchmarks for speed +$ git commit -m "Story 182: fix benchmarks for speed" +[master 463dc4f] Story 182: fix benchmarks for speed 2 files changed, 2 insertions(+) create mode 100644 README ---- -Now you've created your first commit! -You can see that the commit has given you some output about itself: which branch you committed to (`master`), what SHA-1 checksum the commit has (`463dc4f`), how many files were changed, and statistics about lines added and removed in the commit. +حالا شما اولین کامیت خود را ساختید! +می‌توانید ببینید که کامیتی که ساختید چند خروجی درباره خودش به شما می‌دهد: بر روی کدام برنچ کامیت انجام شده است (`master`)، +کد هش SHA-1 خودش (`463dc4f`)، چه مقدار از فایل‌ها تغییر کرده‌اند و آمارهایی درباره خط‌هایی که اضافه یا حذف شده‌اند در همان +کامیت جاری. -Remember that the commit records the snapshot you set up in your staging area. -Anything you didn't stage is still sitting there modified; you can do another commit to add it to your history. -Every time you perform a commit, you're recording a snapshot of your project that you can revert to or compare to later. +به یاد داشته باشید که آن کامیت اسنپ‌شاتی را ثبت می‌کند شما در موقعیت استیج آماده سازی کرده‌اید. +هر چیزی که شما استیج نکرده‌اید همچنان با عنوان فایل تغییر یافته باقی مانده‌ است؛ شما می‌توانید کامیت دیگری بسازید +و آن را به تاریخچه‌ی تغییرات خود اضافه کنید. +هر زمانی که یک کامیت جدید ایفا می‌کنید، شما اسنپ‌شاتی از پروژه خود می‌سازید که در هر زمان می‌توانید پروژه +را به همان اسنپ‌شات برگردانید یا مقایسه کنید. -==== Skipping the Staging Area +==== رد کردن موقعیت استیج (((staging area, skipping))) -Although it can be amazingly useful for crafting commits exactly how you want them, the staging area is sometimes a bit more complex than you need in your workflow. -If you want to skip the staging area, Git provides a simple shortcut. -Adding the `-a` option to the `git commit` command makes Git automatically stage every file that is already tracked before doing the commit, letting you skip the `git add` part: +موقعیت استیج گاهی اوقات شاید آنطور که ما باید انتظار داریم پیش نمی‌رود و بیش از حد شلوغ می‌شود. +اگر می‌خواهید از مرحله استیج کردن فایل‌ها رد شوید و سریع وارد مرحله کامیت شوید، گیت یک شورت‌کات ساده برای شما آماده کرده است. +با اضافه کردن آپشن `a-` به دستور `git commit` باعث می‌شود گیت به صورت اتوماتیک هر فایلی که ترک شده را استیج کند و آماده کامیت کند، +به طور کلی به این آپشن مرحله `git add` را انجام می‌دهد: [source,console] ---- @@ -484,23 +513,26 @@ Changes not staged for commit: modified: CONTRIBUTING.md no changes added to commit (use "git add" and/or "git commit -a") -$ git commit -a -m 'added new benchmarks' -[master 83e38c7] added new benchmarks +$ git commit -a -m 'Add new benchmarks' +[master 83e38c7] Add new benchmarks 1 file changed, 5 insertions(+), 0 deletions(-) ---- -Notice how you don't have to run `git add` on the `CONTRIBUTING.md` file in this case before you commit. -That's because the `-a` flag includes all changed files. -This is convenient, but be careful; sometimes this flag will cause you to include unwanted changes. +دقت کنید که چرا نباید دستور `git add` برای فایل `CONTRIBUTING.md` در این مورد اجرا کنید قبل از اینکه کامیت کنید. +به این دلیل است که آپشن `a-` تمام فایل‌‌هایی است که تغییر کرده‌اند. +این گزینه‌ی راحتی است اما مراقب باشید؛ بعضی وقت‌‌ها باعث می‌شود که شما تغییراتی که نمی‌خواهید را شامل کنید. [[_removing_files]] -==== Removing Files +==== حذف‌ کردن فایل (((files, removing))) -To remove a file from Git, you have to remove it from your tracked files (more accurately, remove it from your staging area) and then commit. -The `git rm` command does that, and also removes the file from your working directory so you don't see it as an untracked file the next time around. -If you simply remove the file from your working directory, it shows up under the ``Changed but not updated'' (that is, _unstaged_) area of your `git status` output: +برای حذف یک فایل از گیت،‌ باید آن را از حالت ترکت حذف کنید(درست‌تر بگوییم، آن را از موقعیت استیج حذف کنید) و بعد کامیت کنید. +دستور `git rm` این کار را می‌کند و همچنین فایل را از پوشه کاریتان حذف می‌کند پس شما آن را به عنوان یک فایل آن‌ترکت شده +نخواهید دید. + +اگر به سادگی فایل را از پوشه کاریتان حذف کنید،‌ نام فایل را زیر تیتر ``Changed but not updated`` می‌بینید +و در خروجی `git status` شما به (آن وضعیت _unstaged_) می‌گوید. [source,console] ---- @@ -517,7 +549,7 @@ Changes not staged for commit: no changes added to commit (use "git add" and/or "git commit -a") ---- -Then, if you run `git rm`, it stages the file's removal: +سپس، اگر دستور `git rm` را اجرا کنید، گیت فایل را با عنوان فایل حذف شده آن را استیج می‌کند: [source,console] ---- @@ -532,58 +564,60 @@ Changes to be committed: deleted: PROJECTS.md ---- -The next time you commit, the file will be gone and no longer tracked. -If you modified the file and added it to the staging area already, you must force the removal with the `-f` option. -This is a safety feature to prevent accidental removal of data that hasn't yet been recorded in a snapshot and that can't be recovered from Git. +دفعه بعد که کامیت کنید، فایل از بین خواهد رفت و دیگر وجود نخواهد داشت. +اگر شما فایل را تغییر دهید و آن را استیج کنید، ـ‌بایدـ از آپشن `f-` استفاده کنید و یه جورایی باید آن را به زور حذف کرد. +این یک امکان امن برای حذف تصادفی اطلاعاتی است که هنوز در هیچ اسنپ‌شاتی ثبتت نشده‌اند و نمی‌توانند نمی‌توانند توسط گیت ثبت شوند. -Another useful thing you may want to do is to keep the file in your working tree but remove it from your staging area. -In other words, you may want to keep the file on your hard drive but not have Git track it anymore. -This is particularly useful if you forgot to add something to your `.gitignore` file and accidentally staged it, like a large log file or a bunch of `.a` compiled files. -To do this, use the `--cached` option: +امکان مفید دیگری شاید بخواهید انجام دهید برای نگه‌داشتن فایل در پوشه کاریتان، اما آن را از محیط استیج حذف کرده‌اید. +در زبانی دیگر، شاید بخوایید آن را در حافظه سخت خود نگه‌دارید ولی نمی‌‌خواهید گیت آن را به هیچ عنوان دنبال کند. +این یک دستور به شدت به درد بخور است چرا اگه فراموش کرده‌اید چیزی را به `gitignore.` اضافه کنید و تصادفا آن را استیج کرده‌اید، +مانند یک فایل لاگ بزرگ یا کلی فایل ‍`a.` کامپایل شده. +به راحتی از آپشن `cached--` استفاده کنید: [source,console] ---- $ git rm --cached README ---- -You can pass files, directories, and file-glob patterns to the `git rm` command. -That means you can do things such as: +شما می‌توانید از الگو‌های پوشه‌ها، فایل‌ها و فایل‌های اصلی در دستور `git rm` استفاده کنید. +که به این معنی است شمامی‌توانید اینگونه عمل کنید: [source,console] ---- $ git rm log/\*.log ---- -Note the backslash (`\`) in front of the `*`. -This is necessary because Git does its own filename expansion in addition to your shell's filename expansion. -This command removes all files that have the `.log` extension in the `log/` directory. -Or, you can do something like this: +به بک‌اسلش(‍`\`) در مقابل `*` دقت کنید. +این کار لازم است چون گیت این کار را به علاوه فایل‌های توسعه خودش بر روی فایل‌های توسعه شما هم اعمال می‌کند. +این دستور تمام فایل‌های توسعه که با پسوند `log.` هستند درون پوشته `/log` را حذف می‌کند. +یا شما می‌توانید چیزی شبیه به دستور زیر را اجرا کنید: [source,console] ---- $ git rm \*~ ---- -This command removes all files whose names end with a `~`. +این دستور تمام فایل‌هایی که نام آن‌ها با یک `~` تمام می‌شود را حذف می‌کند. [[_git_mv]] -==== Moving Files +==== جابه‌جایی فایل‌ها (((files, moving))) -Unlike many other VCS systems, Git doesn't explicitly track file movement. -If you rename a file in Git, no metadata is stored in Git that tells it you renamed the file. -However, Git is pretty smart about figuring that out after the fact -- we'll deal with detecting file movement a bit later. +برعکس خیلی از کنترل نسخه‌های دیگر، گیت به صراحت جابه‌جایی‌ها را دنبال نمی‌کند. +اگر شما فایلی را در گیت تغییر نام‌ دهید، هیچگونه متادیتا‌ای در گیت ذخیر نمی‌شود که بعدا بگوید شما آن را تغییر نام داده‌اید. +با این حال، گیت خیلی باهوش است و به راحتی بعد از این کارا می‌فهمد. -- جلوتر درباره جابه‌جایی فایل‌ها حرف خواهیم زد. -Thus it's a bit confusing that Git has a `mv` command. -If you want to rename a file in Git, you can run something like: +بنابراین شاید یکم گیج کننده باشد که گیت دستوری به نام `mv` دارد. +اگر بخواهید نام یک فایل را در گیت تغییر دهید، می‌توانید دستوری شبیه به زیر را اجرا کنید: [source,console] ---- $ git mv file_from file_to ---- -and it works fine. -In fact, if you run something like this and look at the status, you'll see that Git considers it a renamed file: +و به خوبی کار کرد. +در حقیقت، اگر شما چیزی شبیه دستور زیر را اجرا کنید و وضعیت را بررسی کنید، می‌بینید که گیت آن را به عنوان فایل تغییر نام یافته +در نظر می‌گیرد: [source,console] ---- @@ -597,7 +631,7 @@ Changes to be committed: renamed: README.md -> README ---- -However, this is equivalent to running something like this: +با این حال، این معادل اجرا کردن دستوری شبیه زیر است: [source,console] ---- @@ -606,6 +640,6 @@ $ git rm README.md $ git add README ---- -Git figures out that it's a rename implicitly, so it doesn't matter if you rename a file that way or with the `mv` command. -The only real difference is that `git mv` is one command instead of three -- it's a convenience function. -More importantly, you can use any tool you like to rename a file, and address the add/rm later, before you commit. +گیت فهمید که یک تغییر نام ضمنی است، پس اصلامهم نیست که شما فایلی را با دستور `mv` تغییر نام دهید. +تنها تفاوت اصلی این است که `git mv` یک دستور است به جای سه دستور -- صرفا یک تابع برای آسودگی کار است. +مهم‌تر از هر چیزی این است که شما می‌توانید از هر ابزاری برای تغییر نام یک فایل استفاده کنید. diff --git a/book/02-git-basics/sections/remotes.asc b/book/02-git-basics/sections/remotes.asc index 10b209bf8..c8eb5696c 100644 --- a/book/02-git-basics/sections/remotes.asc +++ b/book/02-git-basics/sections/remotes.asc @@ -1,26 +1,29 @@ [[_remote_repos]] -=== Working with Remotes - -برای همکاری در پروژه های گیت، دانستن شیوه ی مدیریت مخارن راه دور لازم است. -مخازن راه دور یک نسخه از پروژه ی شما هستند که در اینترنت یا جایی دیگر در شبکه قرار دارند. -می توانید جند تا از آنها را داشته باشید که هرکدام فقط خواندی یا با اجزاه خواندن و نوشتن باشد. -همکاری با دیگران شما را با مدیریت این مخازن و دریافت داده از آنها و انتقال داده به آنها درگیر می کند. که بتوانید کارهایتان را به اشتراک بگزارید. -مدیریت مخازن راه دور به مفهوم افزودن مخازن راه دور، حذف کردن مخازن به کار نخور، مدیریت شاخه های گوناگون و تعریف آنها به عنوان دنبال شونده با بر داشتن این تعریف و کارهای دیگر است. -در این بخش، ما به برخی از این وهارتهای مدریت مخازن راه دور خواهیم پرداخت.پ +=== کار کردن با ریموت‌ها +برای همکاری در پروژه‌های گیت، دانستن شیوهٔ مدیریت مخزن‌های ریموت لازم است. +مخازن ریموت یک نسخه از پروژهٔ شما هستند که در اینترنت یا جایی دیگر در شبکه قرار دارند. +می‌توانید چند تا از آنها را داشته باشید که هر کدام یا فقط قابل خواندن یا خواندنی/نوشتی هستند. +همکاری با دیگران شما را با مدیریت این مخازن و دریافت داده از آنها و انتقال‌داده به آنها درگیر می کند. که بتوانید کارهایتان را +به اشتراک بگزارید. +مدیریت مخازن ریموت به مفهوم افزودن مخازن ریموت، حذف کردن مخازن بلا استفاده، مدیریت شاخه‌های گوناگون و تعریف آنها به عنوان دنبال شونده +با بر داشتن این تعریف و کارهای دیگر است. +در این بخش ما درباره برخی از مهارت‌‌های مدیریت-ریموت صبحت خواهیم کرد. [NOTE] -.مخازن راه دور می توانند روی کامپیوتر خودتان باشند. +.مخازن ریموت می‌توانند روی کامپیوتر خودتان باشند. ==== به سادگی امکان پذیر است که شما با مخازن ``remote'' ی کار کنید که در واقع در همان کامپیوتر خودتان قرار دارد. -واژه ی ``remote`` لزوما به معنی این نیست که مخزن دور از دسترس، روی اینترنت یا هرجای دیگر شبکه باشد، تنها به این معنی است که مخزن جای دیگری است. -این گونه مخازن راه دور نیز همانند دیگر مخازن راه دور با مسائل دریافت داده، ارسال داده و عملیات دیگر درگیر هستند. +واژهٔ ``remote`` لزوما به معنی این نیست که مخزن دور از دسترس، روی اینترنت یا هرجای دیگر شبکه باشد، تنها به این معنی است که مخزن +جای دیگری است. +این گونه مخازن ریموت نیز همانند دیگر مخازن ریموت با مسائل دریافت داده، ارسال داده و عملیات دیگر درگیر هستند. ==== -==== Showing Your Remotes +==== نمایش ریموت‌هایتان -برای دیدن سرورهای راه دوری که پیکربندی شده اند، می توانید دستور `git remote` را اجرا کنید.(((git commands, remote))) -این دستور نامهای کوتاه سرورهای راه دوری که شما برگزیدید را نشان خواهد داد. -اگر نسخه ای از یک مخزن راه دور بردارید، باید دست کم یک `origin` ببنیند. -- گیت به شکل پیش فرض به سروری که با آن کار می کند این نام را می دهد: +برای دیدن سرورهای ریموت که پیکربندی شده‌اند، می‌توانید دستور `git remote` را اجرا کنید.(((git commands, remote))) +این دستور نام‌های کوتاه سرورهای ریموتی که شما برگزیدید را نشان خواهد داد. +اگر نسخه‌ای از یک مخزن ریموت بردارید، باید دست کم یک `origin` ببنیند. +-- گیت به شکل پیش فرض به سروری که با آن کار می کند این نام را می دهد: [source,console] ---- @@ -36,7 +39,8 @@ $ git remote origin ---- -همچنین متوانید `-v` را بکار گیرید، این دستور به شما نشانی های URL ی را نشان می دهد که برای خواندن و نوشتن داده های پروژه به کار می روند.. +همچنین متوانید `v-` را بکار گیرید،این دستور به شما نشانی های URL ی را نشان می دهد +که برای خواندن و نوشتن داده های پروژه به کار می روند.. [source,console] ---- @@ -63,17 +67,16 @@ koke git://github.com/koke/grit.git (push) origin git@github.com:mojombo/grit.git (fetch) origin git@github.com:mojombo/grit.git (push) ---- +این به معنی است ما می‌توانیم مشارکت‌هارا از هر کاربری به راحتی پول یا دریافت کنیم. +شاید ما به علاوه دسترسی برای پوش یا ارسال به یک یا بیشتر مخازن داشته باشیم که اینجا نمی‌توانیم بگوییم. +دقت کنید که این ریموت‌ها از پروتکل‌های متنوعی استفاده ‌می‌کنند؛ ما درباره این موضوع در <<_getting_gin_on_a_server>> بیشتر گفته‌ایم. -This means we can pull contributions from any of these users pretty easily. -We may additionally have permission to push to one or more of these, though we can't tell that here. - -Notice that these remotes use a variety of protocols; we'll cover more about this in <<_getting_git_on_a_server>>. - -==== Adding Remote Repositories +==== اضافه کردن مخزن ریموت +ما پیش‌تر درباره چگونه دستور `git clone` به طور غیر مستقیم یک ریموت `origin` برای شمامی‌سازد. +خب حالا میگیم چطور یک مخزن ریموت جدید اضافه کنید. -We've mentioned and given some demonstrations of how the `git clone` command implicitly adds the `origin` remote for you. -Here's how to add a new remote explicitly.(((git commands, remote))) -To add a new remote Git repository as a shortname you can reference easily, run `git remote add `: +برای اضافه کردن یک مخزن گیت ریموت جدید با یک نام کوتاه می‌توانید به آدرس آن اشاره کنید و +تقریبا یک آلیاز از آدرس مخزن با نام کوتاه‌ بسازید. با اجرای دستور `git remote add {shortname} {url}`: [source,console] ---- @@ -86,9 +89,9 @@ origin https://github.com/schacon/ticgit (push) pb https://github.com/paulboone/ticgit (fetch) pb https://github.com/paulboone/ticgit (push) ---- - -Now you can use the string `pb` on the command line in lieu of the whole URL. -For example, if you want to fetch all the information that Paul has but that you don't yet have in your repository, you can run `git fetch pb`: +حالا می‌توانید از `pb` در محیط ترمینال به جای کل آدرس آن مخزن استفاده کنید. +برای مثال، اگر شما بخواهید تمام اطاعاتی که paul دارد را فچ یا دریافت کنید اما هنوز اطلاعات در مخزن خود ندارید، +با اجرای دستور `git fetch pb`: [source,console] ---- @@ -101,54 +104,61 @@ From https://github.com/paulboone/ticgit * [new branch] master -> pb/master * [new branch] ticgit -> pb/ticgit ---- +برنچ `master` پاول حالا به صورت لوکال در `master/pb` قابل دسترس دسترس است -- شما می‌توانید این شاخه را در هر کدام از بر‌نچ‌های دلخواه +ادغام کنید. یا می‌توانید برنچ لوکال خود را چک‌اوت کنید تا اطلاعات را بازرسی کنید. -Paul's master branch is now accessible locally as `pb/master` -- you can merge it into one of your branches, or you can check out a local branch at that point if you want to inspect it. -(We'll go over what branches are and how to use them in much more detail in <<_git_branching>>.) +(ما درباره برنچ‌های و چگونگی استفاده از آن‌ها با جزئیات بیشتر در بخش <<_git_branching>> گفته‌ایم.) [[_fetching_and_pulling]] -==== Fetching and Pulling from Your Remotes -As you just saw, to get data from your remote projects, you can run:(((git commands, fetch))) +==== فچ کردن و پول کردن در یک مخزن ریموت +همانطور که مشاهده کردید، برای دریافت اطلاعات از پروژه‌های ریموت خود،‌می‌توانید این دستور را اجرا کنید: [source,console] ---- $ git fetch ---- +دستور مراجعه می‌کند به پروژه ریموت و همه‌ی اطلاعات آن را پول می‌کند. +بعد از انجام این کار، شما می‌توانید به همه‌ی شاخه‌ها از ریموت مراجعه کنید، که می‌توان در هر لحظه ادغام یا مورد نمایش قرار دهید. -The command goes out to that remote project and pulls down all the data from that remote project that you don't have yet. -After you do this, you should have references to all the branches from that remote, which you can merge in or inspect at any time. +اگر شما یک مخزن را کلون کنید، دستور به صورت خودکار نام مخزن را تحت عنوان `origin` می‌سازد. پس `git fetch origin` تمامی کارها و +اتفاقات جدید که در آن سرور از وقتی که شما آن را کلون کرده‌اید(اخرید فچی که شما داشتید) دریافت می‌کند. +خیلی مهم است که دقت کنید که دستور `git fetch` فقط اطلاعات را در مخزن لوکال شما دریافت می‌کند -- این دستور به صورت خودکار +اطلاعات را با برنچ‌هایی که روی آن کار می‌کنید یا هر برنچ دیگری ادغام نمی‌کند. -If you clone a repository, the command automatically adds that remote repository under the name ``origin''. -So, `git fetch origin` fetches any new work that has been pushed to that server since you cloned (or last fetched from) it. -It's important to note that the `git fetch` command only downloads the data to your local repository -- it doesn't automatically merge it with any of your work or modify what you're currently working on. -You have to merge it manually into your work when you're ready. +اگر از دستور فچ استفاده کردید باید به صورت دستی فعلا مرج یا ادغام را انجام دهید. +اگر برنچ جاری شما تنظیم شده باشد تا یک شاخه ریموت را دنبال کند (بخش بعدی و <<_git_branching>>‌ را برای اطلاعات بیشتر ببینید.)، +می‌توانید از دستور `git pull` به صورت خودکار فعل فچ و ادغام یا مرج آن ریموت در برنچ جاری شما انجام شود. -If your current branch is set up to track a remote branch (see the next section and <<_git_branching>> for more information), you can use the `git pull` command to automatically fetch and then merge that remote branch into your current branch.(((git commands, pull))) -This may be an easier or more comfortable workflow for you; and by default, the `git clone` command automatically sets up your local master branch to track the remote master branch (or whatever the default branch is called) on the server you cloned from. -Running `git pull` generally fetches data from the server you originally cloned from and automatically tries to merge it into the code you're currently working on. +این کار شاید برای شما خیلی راحت‌تر یا مورد استقبال‌تر باشد، و به صورت پیش فرض دستور `git clone` خودکار برنچ مستر لوکال شما را برای +دنبال کردن برنچ مستر(یا هرچی که آن شاخه به صورت پیش فرض نامیده‌ شود) ریموت تنظیم می‌کند. -[[_pushing_remotes]] -==== Pushing to Your Remotes +اجرا کردن `git pull` به صورت کلی تمام اطلاعات را از سروری که شما کلون اصلی را انجام دادید؛ فچ می‌کند و به صورت خودکار سعی می‌کند +به ادغام یا مرج کردن کد‌های سرور در جایی که شما در حال کار کردن هستید. -When you have your project at a point that you want to share, you have to push it upstream. -The command for this is simple: `git push `.(((git commands, push))) -If you want to push your master branch to your `origin` server (again, cloning generally sets up both of those names for you automatically), then you can run this to push any commits you've done back up to the server: +[[_pushing_remotes]] +==== پوش کردن به مخزن‌های ریموت +زمانی که شما پروژه‌ای دارید که می‌خواهید آن را به اشتراک بگذارید، شما باید آن را به آپ‌استریم پوش کنید. +دستور این کار خیلی ساده است: `git push {remote} {branch}`.(((git commands, push))) +اگر می‌خواهید برنچ `master` را به سرور `origin` پوش کنید،(یادتون باشه، اسامی که گفتیم بعد از کلون کردن به صورت اتوماتیک ساخته می‌شوند) +، بعد می‌توانید با اجرای دستور پوش هر دستوری که کامیت کرده‌ بودید را به سمت سرور بفرستید. [source,console] ---- $ git push origin master ---- -This command works only if you cloned from a server to which you have write access and if nobody has pushed in the meantime. -If you and someone else clone at the same time and they push upstream and then you push upstream, your push will rightly be rejected. -You'll have to fetch their work first and incorporate it into yours before you'll be allowed to push. -See <<_git_branching>> for more detailed information on how to push to remote servers. +این دستور فقط زمانی کار می‌کند که شما مخزنی را از سمت سروری کلون کرده باشید که دسترسی نوشتن نیز داشته باشید و اگر کسی در خلال کار +شما پوش نکرده باشد، چرا که وقتی شخصی دیگر از همان مخزن اطلاعات را کلون کرده باشد و پوش هم کرده باشد درخواست پوش شما رد خواهد شد،‌ +به این دلیل که اطلاعات شما باید عین چیزی باشد که بر روی سرور قرار داد یعنی باید به روز باشد پس باید اول اطلاعات سرور را فچ کنید +بعد اجازه دارید اطلاعات خودتون رو به سرور پوش کنید. +برای جزئیات بیشتر در این باره که چطور بر روی یک سرور ریموت پوش کنید بخش <<_git_branching>> را مطالعه کنید. [[_inspecting_remote]] -==== Inspecting a Remote - -If you want to see more information about a particular remote, you can use the `git remote show ` command.(((git commands, remote))) -If you run this command with a particular shortname, such as `origin`, you get something like this: +==== بازرسی ریموت +اگر می‌خواید درباره یک ریموت خاص اطلاعات بیشتری ببینید، می‌توانید از دستور +`git remote shot {remote}` استفاده کنید.(((git commands, remote))) +اگر این دستور را اجرا کنید با یک اسم خاص کوتاه، مثل `origin` چیزی شبیه به این را خواهید دید: [source,console] ---- @@ -166,12 +176,11 @@ $ git remote show origin master pushes to master (up to date) ---- -It lists the URL for the remote repository as well as the tracking branch information. -The command helpfully tells you that if you're on the master branch and you run `git pull`, it will automatically merge in the master branch on the remote after it fetches all the remote references. -It also lists all the remote references it has pulled down. - -That is a simple example you're likely to encounter. -When you're using Git more heavily, however, you may see much more information from `git remote show`: +این دستور آدرس مخزن ریموت و همچنین اطلاعات برنچ‌هایی که دنبال می‌شوند را لیست می‌کند و مفید و مختصر به شما می‌گوید که اگر +بر روی برنچ مستر هستید و دستور `git pull` را اجرا کنید، به صورت اتوماتیک اطلاعات که دریافت می‌کند در برنج مستر شما مرج می‌کند +و همچنین لیست تمام ریموت‌های منبع که از آن پول کرده است را نمایش می‌دهد. +این ساده‌ترین مثالی است که شما با آن برخورد خواهید کرد. +وقتی از گیت در سطح وسیع‌‌تری استفاده کنید،‌احتمالا اطلاعات بیشتری با این دستور به شما نشان داده شود، `git remote show`: [source,console] ---- @@ -196,14 +205,13 @@ $ git remote show origin markdown-strip pushes to markdown-strip (up to date) master pushes to master (up to date) ---- - -This command shows which branch is automatically pushed to when you run `git push` while on certain branches. -It also shows you which remote branches on the server you don't yet have, which remote branches you have that have been removed from the server, and multiple local branches that are able to merge automatically with their remote-tracking branch when you run `git pull`. +این دستور نشان‌ می‌دهد که به کدام برنچ به صورت اتوماتیک پوش شده‌ است وقتی دستور `git push` بر روی یک برنچ مشخص انجام می‌شود. +همچنین کدام برنچ روی سرور را، شما ندارید؛ کدام برنچ بر شما دارید اما از روی سرور حذف شده است. +و چندین برنچ لوکا که می‌توانند به صورت اتوماتیک مرج شوند با برنجی که بر روی آن هستید و این کار با دستو `git pull` اجرایی خواهد شد. ==== Renaming and Removing Remotes - -You can run `git remote rename` to change a remote's shortname.(((git commands, remote))) -For instance, if you want to rename `pb` to `paul`, you can do so with `git remote rename`: +شما می‌توانید دستور `git remote rename` را اجرا کنید تا نام کوتاه ریموت را عوض کنید. +برای نمونه، اگر می‌خواهید جای نام `pb` به `paul` تغییر کند،‌ می‌توانید دستور `git remote rename` را وارد کنید. [source,console] ---- @@ -212,11 +220,11 @@ $ git remote origin paul ---- +قابل ذکر است که دستور بالا نام تمام برنچ‌ها حتی آنهایی که بر روی سرور هستند نیز تغییر می‌کند. +چیزی که برای اشاره از آن استفاده می‌شد از `pb/master` به `paul/master` تغییر می‌کند. -It's worth mentioning that this changes all your remote-tracking branch names, too. -What used to be referenced at `pb/master` is now at `paul/master`. - -If you want to remove a remote for some reason -- you've moved the server or are no longer using a particular mirror, or perhaps a contributor isn't contributing anymore -- you can either use `git remote remove` or `git remote rm`: +اگر بخواهید یک ریموت را به هر دلیلی حذف کنید -- جابه جایی سرور یا قابل استفاده نبود آن یا شاید یک مشارکت کنند دیگر مشارکتی نمی‌کند +-- شما می‌توانید یا از دستور `git remote remove` یا از دستور `git remote rm` استفاده کنید: [source,console] ---- @@ -224,5 +232,4 @@ $ git remote remove paul $ git remote origin ---- - -Once you delete the reference to a remote this way, all remote-tracking branches and configuration settings associated with that remote are also deleted. +یکبار که یک ریموت را به این صورت پاک کنید، تمامی برنچ‌ها و پیکیربندی‌هایی همراه آن وجود داشت نیز از بین خواهند رفت. diff --git a/book/02-git-basics/sections/tagging.asc b/book/02-git-basics/sections/tagging.asc index 2fb85c5fb..cf6aa91d2 100644 --- a/book/02-git-basics/sections/tagging.asc +++ b/book/02-git-basics/sections/tagging.asc @@ -1,27 +1,35 @@ [[_git_tagging]] -=== برجسب گذاری +=== برجسب‌گذاری (((tags))) -همچون دیگر سامانه های کنترل نسخه، گیت هم می تواند یک نقطه ی خاص از تاریخچه ی پروژه را به عنواه نقطه ی مهم و با اهمیت برچسب گذاری کند. -معمولا افراد از این قابلیت برای نشانه گذاری نسخه های قابل ارائه یا همان release کردن پروژه بهره می برند.( نسخه v1.0، و به همین ترتیب). -در این بخش یاد فهرست گرفتن از برچسب های موجود، شیوه ساخت برچسب جدید و این که گونه های متفاوت برچسب ها هر کدام چه هستند را یاد خواهید گرفت. -==== فهرست برچسب های موجود +مانند بیشتر VCSهای دیگر، گیت قابلیت برچسب‌زدن (Tag/تگ) نقاطی خاص از پروژه را به عنوان نقاط مهم دارد. +معمولاً افراد از این قابلیت برای نشانه‌گذاری نسخه‌های قابل ارائه یا _release_ استفاده می‌کنند (`v1.0`، `v2.0` و به همین ترتیب). +در این بخش می‌آموزید که چگونه تگ‌های از پیش موجود را لیست کنید، چگونه تگ بسازید و از بین ببرید و اینکه انواع مختلف تگ‌ها کدامند. + -فهرست گیری از برچسب هیا موجود در گیت بسیار ساده است. تنها نیاز است که دستور `git tag` (با پارامتر دلخواه `-l` و یا `--list`) را وارد نمایید:(((git commands, tag))) +همچون دیگر سیستم‌های کنترل نسخه، گیت هم می‌تواند یک نقطه‌ی خاص از تاریخچهٔ پروژه +را به عنواه نقطهٔ مهم و با اهمیت برچسب گذاری کند. +معمولا افراد از این قابلیت برای نشانه گذاری نسخه‌های قابل ارائه یا همان release کردن پروژه بهره می‌برند. +( نسخه v1.0، و به همین ترتیب). +در این بخش فهرست‌سازی از برچسب‌های موجود، شیوه ساخت برچسب جدید و این که گونه‌های متفاوت برچسب ها +هر کدام چه هستند را یاد خواهید گرفت. + +==== فهرست برچسب های موجود +فهرست‌‌سازی از برچسب‌های موجود در گیت بسیار ساده است. تنها نیاز است که دستور `git tag` +(با پارامتر دلخواه `-l` و یا `--list`) را وارد نمایید:(((git commands, tag))) [source,console] ---- $ git tag -v0.1 -v1.3 +v1.0 +v2.0 ---- -این دستور، برچسب های موجود را به ترتیب حرف الفبا نشان می دهد; درواقع ترتیب نمایش آنها هیچ اهمیت ندارد. - -همچنین می توان برچسب ها را جست و جو کنید و از قواعد الگوها نیز بهره مند شود. +این دستور، برچسب های موجود را به ترتیب حرف الفبا نشان می دهد; درواقع ترتیب نمایش آنها هیچ اهمیتی ندارد. +همچنین می توان برچسب ها را جست و جو کنید و از الگوها نیز بهره‌مند شوید. برای نمونه مخزن اصلی گیت، بیش از 500 برچسب دارد. -مثلا اگر میخواید تنها به دنبال برجسب های سری 1.8.5 بگردید، می توانید دستور زیر را اجرا نمایید. +مثلا اگر می‌خواید تنها به دنبال برجسب‌های سری 1.8.5 بگردید، می‌توانید دستور زیر را اجرا نمایید: [source,console] ---- @@ -39,30 +47,36 @@ v1.8.5.5 ---- [NOTE] -.Listing tag wildcards requires `-l` or `--list` option ==== -If you want just the entire list of tags, running the command `git tag` implicitly assumes you want a listing and provides one; the use of `-l` or `--list` in this case is optional. +آپشن `l-` یا `list--` یک الگو خاص را می‌تواند لیست کند. -If, however, you're supplying a wildcard pattern to match tag names, the use of `-l` or `--list` is mandatory. +اگر می‌خواهید لیستی از تگ‌ها را لیست کنید، با اجرا کردن دستور `git tag` به سرعت یک لیست برای شما تهیه می‌کند؛ استفاده از آپشن‌های `l-` +یا `list--` اختیاری است. + +با این حال اگر خواستید یک لیستی مشخص با یک الگو را ببینید، استفاده از آپشن `l-` یا `list--` لازم است. ==== -==== ساخت برچسب ها +==== ساخت برچسب‌ها -گیت دو گونه برچسب دارد: _lightweight_ یا __سبک__ و _annotated_ یا __مفصل__. +گیت دو گونه برچسب دارد: _lightweight_ یا __موقت__ و _annotated_ یا __توضیحی__. -یگ برچسب lightweight بسیار شبیه یک شاخه ی بدون تغییر است. -- فقط اشاره گری به یک ثبت ویژ] و مشخص است. +یک تگ موقت بسیار شبیه یک برنچ است که تغییر نمی‌کند -- فقط یک اشاره‌گر به کامیتی مشخص است. -برچسب های Annotated , however, به عنوان مجموعه ای از اشیاء کامل در پایگاه داده گیت ذخیره می شوند. -این برچسب ها کنترل checksum می شوند; شامل نام کاربر، ایمیل و تاریخ برجسب گذاری هستند; پیام مربوط به برچسب را دارند; و می توان آنها را با GPG (GNU Privacy Guard) علامت گذاری و تایید نمود. +با این حال، تگ‌‌‌های توضیحی به عنوان یک آبجکت کامل در دیتابیس گیت ذخیره می‌شوند؛ که این آبجکت‌ها شامل نام و ایمیل کسی که تگ را ثبت کرده، +تاریخ ثبت تگ و دارای پیام مربوط به خود هستند و همچنین می‌توانند امضا شوند یا توسط گادر حریم خصوصی گنو یا GPG تایید شوند. +به طور کلی پیشنهاد می‌شود که از تگ توضیحی استفاده کنید که در نتیجه‌ می‌توانید تمام اطلاعات ذکر شده را داشته باشید؛ اما اگر لازم شد +که یک تگ موقت ثبت کنید بنا به دلایلی که نمی‌خواهید دیگر اطلاعات را نگه‌دارید، می‌توانید از تگ موقت استفاده کنید. -بیشتر پیشنهاد می شود که برچسب های annotated ایجاد کنید تا به همه این داده ها دسترسی داشته باشد; اما اگر تنها یک برچسب موفت و گذرا نیاز دارید و یا به هر روی نباید داده ها ذخیره شوند می توانید از برچسب های lightweight بهره بگیرید. +بیشتر پیشنهاد می شود که تگ‌‌های توضیحی ایجاد کنید تا به همه این داده ها دسترسی داشته باشد; [[_annotated_tags]] -==== برچسبهای Annotated +==== برچسب‌های توضیحی (((tags, annotated))) -ساخت یک برچسب Annotated در گیت بسیار ساده است. -ساده ترین راه افزدون `-a` هنگام اجرای دستور `tag` می باشد:(((git commands, tag))) +ساخت یک برچسب توضیحی در گیت بسیار ساده است. +ساده‌ترین راه افزدون آپشن `a-` هنگام اجرای دستور `git tag`می باشد: + +(((git commands, tag))) [source,console] ---- @@ -73,10 +87,10 @@ v1.3 v1.4 ---- -`-m` مشخص گننده پیام برچسب است، که با برچسب ذخیره خواهد شد. -اگر پیامی برای یک برچسب annotated مشخص نکنید گیت ویرایش پیش فرض را اجرا کرده و شما می توانید آنجا نوشتن را بیاغازید. +با آپشن `m-` می‌توانید همراه دستور `git tag` پیام برچسب را در یک خط بنویسید اما اگر این آپشن را برای یک تگ توضیحی مشخص نکنید، +گیت ویرایشگر متن شما را برای نوشتن پیام تگ باز خواهد کرد. -داده های برچسب را میتوانید در همان ثبت برچسب گذاری شده با دستور `git show` ببینید. +شما می‌توانید اطلاعات مربوط به تگ‌ها و کامیت‌های مربوط به آن تگ را با استفاده از دستور `git show` ببینید. [source,console] ---- @@ -91,18 +105,16 @@ commit ca82a6dff817ec66f44342007202690a93763949 Author: Scott Chacon Date: Mon Mar 17 21:52:11 2008 -0700 - changed the version number + Change version number ---- +این دستور داده‌هایی اعم از اطلاعات کاربر, تاریخی که تگ کامیت شده است و یادداشت‌‌ها قبل از نمایش اطلاعات کامیت. -این دستور داده های کاربر برچسب گذار، تاریخ برچسب -گذاری و پیام مربوط به برچسب را پیش ا ز داده های ثبت مربوطه نشان می دهد. - -==== برچسب های Lightweight +==== برچسب‌های موقت (((tags, lightweight))) -راه دیگری برای برچسب گذاری ثبت ها برچسب lightweight است. -این برچسب تنها checksum مربوط به ثبت است که در یک فایل ذخیره می شود -- اطلاعات دیگری نگه داشته نمیشود. -برای ساخت یک برچشب lightweight، هیچکدام از گزینه های `-a`، `-s`، یا `-m` را بکار نگیرید، تنها نام برچسب را وارد نمایید. +راه دیگری برای برچسب گذاری کامیت‌ها تگ موقت است. +این تگ تنها مربوط به یک کامیت است که در یک فایل ذخیره می شود -- اطلاعات دیگر مانند تگ توضیحی نگه‌داشته نمی‌شود. +برای ساخت یک برچشب موقت، هیچکدام از آپشن‌های `a-` و `s-`، یا `m-` را بکار نگیرید، فقط نام برچسب را وارد نمایید. [source,console] ---- @@ -114,9 +126,10 @@ v1.4 v1.4-lw v1.5 ---- +در این لحظه، اگر شما دستور `git show` بر روی یک تگ اجرا کنید؛ اطلاعات اضافی نمی‌بینید. -اکنو اگر `git show` را بر روی یک برچسب اجرا کنید، داده های بیشتری از برچسب را نخواهید دید.(((git commands, show))) -این دستور تنها ثبت را نشان خواهد: +این دستور فقط کامیت‌ را نشان می‌دهد: +(((git commands, show))) [source,console] ---- @@ -125,40 +138,41 @@ commit ca82a6dff817ec66f44342007202690a93763949 Author: Scott Chacon Date: Mon Mar 17 21:52:11 2008 -0700 - changed the version number + Change version number ---- -==== برچسب گذاری با تاخیر +==== بعدا تگ بزنید + +شما این امکان را دارید که بعد از چند کامیت، کامیت‌ها قبلی را تگ بزنید. -همچینین می توانید بعد از چند ثبت،ثبت های پیشین را برچسب گذاری کتید. -فرض کنید تاریخچه ی برچسب های شما شبیه این باشد: +فرض کنید تاریخچهٔ تگ‌های شما شبیه این باشد: [source,console] ---- $ git log --pretty=oneline 15027957951b64cf874c3557a0f3547bd83b3ff6 Merge branch 'experiment' -a6b4c97498bd301d84096da251c98a07c7723e65 beginning write support -0d52aaab4479697da7686c15f77a3d64d9165190 one more thing +a6b4c97498bd301d84096da251c98a07c7723e65 Create write support +0d52aaab4479697da7686c15f77a3d64d9165190 One more thing 6d52a271eda8725415634dd79daabbc4d9b6008e Merge branch 'experiment' -0b7434d86859cc7b8c3d5e1dddfed66ff742fcbc added a commit function -4682c3261057305bdd616e23b64b0857d832627b added a todo file -166ae0c4d3f420721acbb115cc33848dfcc2121a started write support -9fceb02d0ae598e95dc970b74767f19372d61af8 updated rakefile -964f16d36dfccde844893cac5b347e7b3d44abbc commit the todo -8a5cbc430f1a9c3d00faaeffd07798508422908a updated readme +0b7434d86859cc7b8c3d5e1dddfed66ff742fcbc Add commit function +4682c3261057305bdd616e23b64b0857d832627b Add todo file +166ae0c4d3f420721acbb115cc33848dfcc2121a Create write support +9fceb02d0ae598e95dc970b74767f19372d61af8 Update rakefile +964f16d36dfccde844893cac5b347e7b3d44abbc Commit the todo +8a5cbc430f1a9c3d00faaeffd07798508422908a Update readme ---- -اینک فرض کنید که در ثبت ``updated rakefile`` فراموش کرده اید پروژ] را با v1.2 برچسب گذاری نمایید. -Now, suppose you forgot to tag the project at v1.2, which was at the ``updated rakefile'' commit. -پس از ثبت می توانید این کار را انجام دهید. -برای برچسب گذاری ثبت های پیشین، checksum مربوط به ثبت را (یا بخشی از آن را ) در پایان دستور وارد نمایید. +حالا فرض کنید که در کامیت ``updated rakefile`` فراموش کرده‌اید پروژ را با v1.2 تگ گذاری کنید. +پس از کامیت می‌توانید این کار را انجام دهید. + +برای تگ کردن کامیت مورد نظر، هش کد کامیت مورد نظر را در اخر دستور وارد کنید. [source,console] ---- $ git tag -a v1.2 9fceb02 ---- -می بینید که ثبت مورد نظر برچسب گذاری شده است:(((git commands, tag))) +می بینید که کامیت مورد نظر تگ گذاری شده است:(((git commands, tag))) [source,console] ---- @@ -180,16 +194,16 @@ commit 9fceb02d0ae598e95dc970b74767f19372d61af8 Author: Magnus Chacon Date: Sun Apr 27 20:43:35 2008 -0700 - updated rakefile + Update rakefile ... ---- [[_sharing_tags]] -==== اشتراک گذری برجسب ها +==== اشتراک گذری تگ‌ها -دستور `git push` برچسب ها را به صورت پیش فرض به سرور منتقل نمی کند.(((git commands, push))) -شما باید برچسب ها را پس از ساخت و ایجاد آنها، مستقلا انتقال دهید. -این فرآیند دقیقا شبیه انتقال و انتشار شاخه هاست -- شما می توانید دستور `git push origin ` را بکار ببرید. +دستور `git push` تگ‌ها را به صورت پیش فرض به سرور منتقل نمی کند.(((git commands, push))) +شما باید تگ‌ها را پس از ساخت و ایجاد آنها، مستقلا انتقال دهید. +این فرآیند دقیقا شبیه انتقال و انتشار شاخه‌ها است -- شما می‌توانید دستور `git push origin {tagname}` را بکار ببرید. [source,console] ---- @@ -204,8 +218,8 @@ To git@github.com:schacon/simplegit.git ---- -اگر برچسب های زیادی دارید که میخواهید همه را یکجا به سرور منتقل کنید، می توانید از گزینه `--tags` در دستور `git push` استفاده نمایید. -این دستور تمام برچسب هایی را که در سرور نیستند به سرور منتقل خواهد کرد. +اگر تگ‌های زیادی دارید که می‌خواهید همه را یکجا به سرور منتقل کنید، می‌توانید از گزینهٔ `tags--` در دستور `git push` استفاده نمایید. +این دستور تمام تگ‌هایی را که در سرور نیستند به سرور منتقل خواهد کرد. [source,console] ---- @@ -218,11 +232,52 @@ To git@github.com:schacon/simplegit.git * [new tag] v1.4-lw -> v1.4-lw ---- -اینک اگر کسی دیگر از مخزن ما نمونه برداری کرد یا تنها ثبت ها را فراخوانی و بارگزاری کرد، تمام برجسب ها را نیز دریافت خواهد نمود. +حالا اگر شخصی دیگر از مخزن ما کلون کند یا آن را پول کند، تمامی تگ‌های ساخته شده نیز وجود خواهند داشت. + +[NOTE] +==== + +دستور `git push` هر دو نوع تگ را به سرور خواهد فرستاد. + +فرستادن تگ‌ها به سمت سرور با دستور `git push {tagname} --tags` هیچ وجه تمایزی بین تگ توضیحی یا تگ موقت قائل نمی‌شود. +هیچ راه یا آپشن ساده‌ای وجود ندارد که نوع تگ مورد نظر برای پوش انتخاب کنید. +==== + +==== حذف کردن تگ‌ها +برای حذف تگ‌های ساخت شدن در مخزن محلی لوکال خود، می‌توانید از دستور `git tag -d {tagname}`. برای مثال، ما می‌توانیم تگ‌های موقت خود را +با دستور زیر حذف کنیم. + +[source,console] +---- +$ git tag -d v1.4-lw +Deleted tag 'v1.4-lw' (was e7d5add) +---- + +دقت کنید که دستور بالا تگ را از مخزن‌های ریموت پاک نمی‌کند و فقط شامل مخزن لوکال می‌شود. +دو راه برای معمول برای حذف تگ از ریموت سرور وجود دارد. + +اولین ایجاد تغییر با دستور `git push {remote} :refs/tags/{tagnam}`: + +[source,console] +---- +$ git push origin :refs/tags/v1.4-lw +To /git@github.com:schacon/simplegit.git + - [deleted] v1.4-lw +---- + +اتفاقی که در بالا می‌افتد این است که قبل از پوش شدن کلون به سمت ریموت سرور مقدار تگ تعیین شده تهی می‌شود. + +راه دوم و منطقی‌ترین راه برای حذف تگ از یک ریموت دستور زیر است. + +[source,console] +---- +$ git push origin --delete +---- -==== Checking out Tags +==== بررسی صحت تگ‌ها -اگر نسخه های فایلهایی که برچسب به آنها اشاره می کند را می خواهید ببینید، می توانید یک git checkout اجرا کنید، آگاه باشید که این کار مخزن شما را در وضعیت **detached HEAD** قرار میدهد, که امکان تاثیر جانبی ناپسندی دارد.: +اگر نسخه‌های فایلهایی که تگ به آنها اشاره می‌کند را می‌خواهید ببینید، می‌توانید یک `git checkout` اجرا کنید، +آگاه باشید که این کار مخزن شما را در وضعیت «**detached HEAD**» قرار می‌دهد, که امکان تاثیرات جبران ناپذیری دارد: [source,console] ---- @@ -242,10 +297,13 @@ HEAD is now at 99ada87... Merge pull request #89 from schacon/appendix-final $ git checkout 2.0-beta-0.1 Previous HEAD position was 99ada87... Merge pull request #89 from schacon/appendix-final -HEAD is now at df3f601... add atlas.json and cover image +HEAD is now at df3f601... Add atlas.json and cover image ---- -در وضعیت **detached HEAD** اگر تغییراتی ایجاد کنید و آنها را ثبت کنید، برچسب تغییر نخواهد کرد، ولی ثبت جدید در هیچ شاخه ای جای نمیگیرد و از دسترس خارج میشود، مگر با کد کامل hash مربوط به آن ثبت. بنابراین اگر نیاز به ایجاد تغییرات دارید -- مثلا میخواهید یک باگ را در نسخه های پیشین برطرف نمایید -- شماه باید یک شاخه ی جدید بسازید. +در وضعیت «**detached HEAD**» اگر تغییراتی ایجاد کنید و آنها را کامیت کنید، +تگ تغییر نخواهد کرد، اما کامیت شما در هیچ کدام از شاخه‌ها ثبت نخواهد شد و از دست می‌رود. +مگر با کد کامل hash مربوط به آن کامیت. بنابراین اگر نیاز به ایجاد تغییرات دارید +-- مثلا می‌خواهید یک باگ را در نسخه‌های پیشین برطرف نمایید -- شماه باید یک شاخهٔ جدید بسازید. [source,console] ---- @@ -253,4 +311,5 @@ $ git checkout -b version2 v2.0.0 Switched to a new branch 'version2' ---- -با اجرای دستور بالا، اگر یک ثبت تازه ایجاد نمودید، شاخه ی `version2` اندکی متفاوت از برچسب `v2.0.0` خواهد بود. تا زمانی که با تغییرات جدید در این شاخه به پیش می رود. پس مرافب باشید. +اگر دستور بالا را اجرا کنید و یک کامیت بسازید، شاخه `version2` از زمانی که شروع به پیشرفت کند مقداری کمی متفاوت +از تگ `v2.0.0` خواهد بود، پس مراقب تغییرات باشید که از دست نروند. diff --git a/book/02-git-basics/sections/undoing.asc b/book/02-git-basics/sections/undoing.asc index a328fe2fe..42a435506 100644 --- a/book/02-git-basics/sections/undoing.asc +++ b/book/02-git-basics/sections/undoing.asc @@ -24,7 +24,7 @@ As an example, if you commit and then realize you forgot to stage the changes in [source,console] ---- -$ git commit -m 'initial commit' +$ git commit -m 'Initial commit' $ git add forgotten_file $ git commit --amend ---- @@ -92,7 +92,7 @@ However, in the scenario described above, the file in your working directory is ===== For now this magic invocation is all you need to know about the `git reset` command. -We'll go into much more detail about what `reset` does and how to master it to do really interesting things in <<_git_reset>>. +We'll go into much more detail about what `reset` does and how to master it to do really interesting things in <>. ==== Unmodifying a Modified File @@ -130,12 +130,12 @@ You can see that the changes have been reverted. [IMPORTANT] ===== It's important to understand that `git checkout -- ` is a dangerous command. -Any changes you made to that file are gone -- Git just copied another file over it. -Don't ever use this command unless you absolutely know that you don't want the file. +Any local changes you made to that file are gone -- Git just replaced that file with the most recently-committed version. +Don't ever use this command unless you absolutely know that you don't want those unsaved local changes. ===== -If you would like to keep the changes you've made to that file but still need to get it out of the way for now, we'll go over stashing and branching in <<_git_branching>>; these are generally better ways to go. +If you would like to keep the changes you've made to that file but still need to get it out of the way for now, we'll go over stashing and branching in <>; these are generally better ways to go. Remember, anything that is _committed_ in Git can almost always be recovered. -Even commits that were on branches that were deleted or commits that were overwritten with an `--amend` commit can be recovered (see <<_data_recovery>> for data recovery). +Even commits that were on branches that were deleted or commits that were overwritten with an `--amend` commit can be recovered (see <> for data recovery). However, anything you lose that was never committed is likely never to be seen again. diff --git a/book/02-git-basics/sections/viewing-history.asc b/book/02-git-basics/sections/viewing-history.asc index 9acd7681d..2d16bc82e 100644 --- a/book/02-git-basics/sections/viewing-history.asc +++ b/book/02-git-basics/sections/viewing-history.asc @@ -1,11 +1,11 @@ [[_viewing_history]] -=== دیدن تاریخچه ی ثبت ها +=== دیدن تاریخچهٔ کامیت‌ها -پس از اینکه چندین ثبت ساختید، یا شاید یک مخزن را که خود تارخچه ای از ثبت ها را در بر دارد، کپی کردید، شاید بخواهید ببینید که در ثبت های پیشین جه پیش آمده است. +پس از اینکه چندین کامیت انجام دادید، یا شاید یک مخزن را که خود تارخچه‌ای از کامیت‌ها را در بر دارد، کلون کردید، شاید بخواهید ببینید که در کامیت‌های پیشین چه پیش آمده است. یک ابزار بسیار اساسی و قدرتمند برای این کار دستور `git log` است. -در این مثال یک پروژه بسیار ساده به نام ``simplegit'' را می بینیم. -برای داشتن پروژه تنها دستور زیر را اجرا کنید: +در این مثال از یک پروژه بسیار ساده به نام «simplegit» استفاده میکنیم. +برای دریافت پروژه دستور زیر را اجرا می‌کنیم. [source,console] ---- @@ -21,29 +21,30 @@ commit ca82a6dff817ec66f44342007202690a93763949 Author: Scott Chacon Date: Mon Mar 17 21:52:11 2008 -0700 - changed the version number + Change version number commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7 Author: Scott Chacon Date: Sat Mar 15 16:40:33 2008 -0700 - removed unnecessary test + Remove unnecessary test commit a11bef06a3f659402fe7563abf99ad00de2209e6 Author: Scott Chacon Date: Sat Mar 15 10:31:28 2008 -0700 - first commit + Initial commit ---- -هنگامی که دستور `git log` را بدون هیچ پیشوند و پسوندی بکار می گیرید، ثبت های موجود در مخرن به ترتیب زمانی معکوس نمایش داده می شوند -- یعنی ثبت های اخیر بالاتر و زودتر نمایش داده می شوند. -همان گونه که می بینید، این دستور ثبت ها را به همراه کد SHA-1، نام و ایمیل نویسنده، تاریخ نگارش و متن پیام ثبت نشان میدهد. +به صورت پیش‌فرض دستور `git log` بدون هیچ آرگومانی کامیت‌های به ثبت رسیده در مخزن را از جدید‌ترین تا قدیمی‌ترین لیست می‌کند؛ یعنی جدیدترین کامیت اولین به نمایش در می‌آید. +همانطور که مشاهده می‌کنید این دستور کامیت‌ها را به همراه هش کد SHA-1، نام و ایمیل نویسنده، تاریخ کامیت و پیام کامیت لیست می‌کند. -دستور `git log` برای برآوردن نیاز شما و نشان دادن هر آنجه که به دنبال آن هستید، گزینه های فراوان و گوناگونی دارد. -در این ما چندتا از پرکاربردهایشان را به شما نشان می دهیم. +گستردگی آپشن‌ها و فلگ(flag)های موجود برای دستور `git log` همان چیزی که به دنبالش هستید را به شما +تحویل می‌دهد. در ادامه چند مورد از پر استفاده‌ترین آن‌ها را نشان می‌دهیم. -یک گزینه سودمند که می تواند تفاوتهای موجود در هر ثبت را نشان دهد گزینه `p` یا `--patch` است. -همچنین می توانید تعداد ردیف های نمایش داده شده را محدود کنید، برای نمونه با `2` برای نمایش داده دو ورودی آخر. +یکی از آپشن جالب و سودمند آپشن `p-` یا `patch--` است که تفاوت‌ها در هر کامیت را نشان می‌دهد. +همچنین شما می‌توانید برای تعداد نمایش کامیت‌ها محدود ایجاد کنید. +برای مثال استفاده از فلگ `2-` فقط دو کامیت آخر را نشان می‌دهد. [source,console] ---- @@ -52,7 +53,7 @@ commit ca82a6dff817ec66f44342007202690a93763949 Author: Scott Chacon Date: Mon Mar 17 21:52:11 2008 -0700 - changed the version number + Change version number diff --git a/Rakefile b/Rakefile index a874b73..8f94139 100644 @@ -72,7 +73,7 @@ commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7 Author: Scott Chacon Date: Sat Mar 15 16:40:33 2008 -0700 - removed unnecessary test + Remove unnecessary test diff --git a/lib/simplegit.rb b/lib/simplegit.rb index a0a60ae..47c6340 100644 @@ -89,10 +90,10 @@ index a0a60ae..47c6340 100644 -end ---- -This option displays the same information but with a diff directly following each entry. -This is very helpful for code review or to quickly browse what happened during a series of commits that a collaborator has added. -You can also use a series of summarizing options with `git log`. -For example, if you want to see some abbreviated stats for each commit, you can use the `--stat` option: +این آپشن همان اطلاعات را نشان می‌دهد، لکن درجا پس از نمایش یک دیف (تفاوت) به ازای هر مقدار می‌گیرد و بسیار سودمند است چرا که برای بازنگری کد +یا جست‌وجو سریع برای فهمیدن اینکه به دنباله مجموعه‌ای از کامیت‌ها که یک تیم انجام داده‌اند چه اتفاقی رخ داده است. +همچنین شما می‌توانید از مجموعه‌ای از چکیده آپشن‌ها استفاده کنید. +برای مثال-- اگر بخواهید ببینید که خلاصه هر کدام چیست، میتوانید از آپشن `stat--` استفاده کنید. [source,console] ---- @@ -101,7 +102,7 @@ commit ca82a6dff817ec66f44342007202690a93763949 Author: Scott Chacon Date: Mon Mar 17 21:52:11 2008 -0700 - changed the version number + Change version number Rakefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) @@ -110,7 +111,7 @@ commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7 Author: Scott Chacon Date: Sat Mar 15 16:40:33 2008 -0700 - removed unnecessary test + Remove unnecessary test lib/simplegit.rb | 5 ----- 1 file changed, 5 deletions(-) @@ -119,7 +120,7 @@ commit a11bef06a3f659402fe7563abf99ad00de2209e6 Author: Scott Chacon Date: Sat Mar 15 10:31:28 2008 -0700 - first commit + Initial commit README | 6 ++++++ Rakefile | 23 +++++++++++++++++++++++ @@ -127,92 +128,101 @@ Date: Sat Mar 15 10:31:28 2008 -0700 3 files changed, 54 insertions(+) ---- -As you can see, the `--stat` option prints below each commit entry a list of modified files, how many files were changed, and how many lines in those files were added and removed. -It also puts a summary of the information at the end. +همانطور که مشاهده کردید، آپشن `stat--` در بالا اطلاعاتی درباره لیست فایل‌های تغییر داده شده، +چه مقدار فایل‌ها مورد تغییر قرار گرفته‌اند و چه تعداد خط به فایل‌ها اضافه یا حذف شده را نمایش می‌دهد. +همچنین در آخر چکیده‌ای از اطلاعات کامیت را قرار می‌دهد. -Another really useful option is `--pretty`. -This option changes the log output to formats other than the default. -A few prebuilt options are available for you to use. -The `oneline` option prints each commit on a single line, which is useful if you're looking at a lot of commits. -In addition, the `short`, `full`, and `fuller` options show the output in roughly the same format but with less or more information, respectively: +یکی دیگر از آپشن‌ها مفید و جالب `pretty--` است. +این آپشن نوع فرمت خروجی به حالت دیگری غیر از حالت پیش فرض تغییر می‌دهد. +چندی از آپشن‌های از پیش ساخته شده برای این فلگ برای استفاده در دسترس شما هستند. +آپشن `oneline` هر کامیت را بر روی یک خط چاپ می‌کند، که بسیار مفید است به خصوص اگر به دنبال حجم زیادی از کامیت‌هاباشید. +و در ادامه و علاوه‌بر آنها، آپشن‌های `short`, `full` and `fuller` خروجی همانگونه که در مثال‌‌ها قبل دیدید نمایش می‌دهد با +اطلاعات کمتر یا بیشتر و به ترتیب: [source,console] ---- $ git log --pretty=oneline -ca82a6dff817ec66f44342007202690a93763949 changed the version number -085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7 removed unnecessary test -a11bef06a3f659402fe7563abf99ad00de2209e6 first commit +ca82a6dff817ec66f44342007202690a93763949 Change version number +085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7 Remove unnecessary test +a11bef06a3f659402fe7563abf99ad00de2209e6 Initial commit ---- -The most interesting option is `format`, which allows you to specify your own log output format. -This is especially useful when you're generating output for machine parsing -- because you specify the format explicitly, you know it won't change with updates to Git:(((log formatting))) +یکی از جالب‌ترین آپشن‌ها `format` است که به شما اجازه می‌دهد نوع فرمت خروجی لاگ را مشخص کنید به خصوص وقتی که می‌خواهید خروجی را +برای ماشین بسازید -- چون شما فرمت را به صراحت تعیین می‌کنید، حتی با آپدیت گیت نیز تغییر نخواهد کرد:(((log formatting))) [source,console] ---- $ git log --pretty=format:"%h - %an, %ar : %s" -ca82a6d - Scott Chacon, 6 years ago : changed the version number -085bb3b - Scott Chacon, 6 years ago : removed unnecessary test -a11bef0 - Scott Chacon, 6 years ago : first commit +ca82a6d - Scott Chacon, 6 years ago : Change version number +085bb3b - Scott Chacon, 6 years ago : Remove unnecessary test +a11bef0 - Scott Chacon, 6 years ago : Initial commit ---- -<> lists some of the more useful options that `format` takes. + +<> لیستی از آپشن مفید بیشتری که فلگ `format` اختیار می‌کند. [[pretty_format]] -.Useful options for `git log --pretty=format` +.آپشن‌های مفید برای`git log --pretty=format` [cols="1,4",options="header"] -|================================ -| Option | Description of Output -| `%H` | Commit hash -| `%h` | Abbreviated commit hash -| `%T` | Tree hash -| `%t` | Abbreviated tree hash -| `%P` | Parent hashes -| `%p` | Abbreviated parent hashes -| `%an` | Author name -| `%ae` | Author email -| `%ad` | Author date (format respects the --date=option) -| `%ar` | Author date, relative -| `%cn` | Committer name -| `%ce` | Committer email -| `%cd` | Committer date -| `%cr` | Committer date, relative -| `%s` | Subject -|================================ - -You may be wondering what the difference is between _author_ and _committer_. -The author is the person who originally wrote the work, whereas the committer is the person who last applied the work. -So, if you send in a patch to a project and one of the core members applies the patch, both of you get credit -- you as the author, and the core member as the committer. -We'll cover this distinction a bit more in <<_distributed_git>>. - -The `oneline` and `format` options are particularly useful with another `log` option called `--graph`. -This option adds a nice little ASCII graph showing your branch and merge history: +|========================== +| ‌آپشن | توضیحات + +| `%H` | هش کد کامیت +| `%h` | خلاصه شده هش کد کامیت +| `%T` | درخت هش +| `%t` | خلاصه شده درخت هش +| `%P` | هش کد پدر +| `%p` | خلاصه شده هش کد پدر +| `%an` | نام نویسنده +| `%ae` | ایمیل نویسنده +| `%ad` | تاریخ اصلی کامیت (با توجه به فرمت `date--`) +| `%ar` | تاریخ اصلی کامیت و وابستگی‌ها +| `%cn` | نام کامیت‌کننده +| `%ce` | ایمیل کامیت‌کننده +| `%cd` | تاریخ آخرین تغییر کامیت ثبت‌شده +| `%cr` | تاریخ اخرین کامیت ثبت‌شده و وابستگی‌ها +| `%s` | موضوع +|========================== + +شاید اول درباره `author` و `committer` متعجب شید و تفاوت آن دو را به خوبی درک نکنید. + +نویسنده یا _author_ در واقع شخصی اصلی بوده است که کار را انجام داده به طور مثال کد برنامه را نوشته، در حالی که +کامیت‌کننده یا _committer_ شخصی است که فعل کامیت را انجام داده و تغییرات را تایید کرده است این دو می‌توانند هر کدام +شخص متفاوتی باشند و یا هر دو یک نفر باشند. +پس اگر شما یک تیکه کد جدید به پروژه اضافه کنید و یکی از اعضای هسته پروژه آن قسمت را تایید کند هر دوی شما دارای اعتبار می‌شوید. +شما به عنوان نویسنده آن و عضو هسته به عنوان شخص کامیت کننده. +درمورد تشخیص بهتر فرق آن دو در قسمت <> به طور مفصل بحث شده است. + +آپشن `oneline` و `format` به طور ویژه‌ای با آپشنی دیگری از فعل ‍`log` مورد استفاده قرار می‌گیرد به نام `graph--`. +این آپشن یک گراف ASCII کوچک و تمیز و زیبا برای نمایش شاخه‌ها و تاریخچه مرج نشان می‌دهد: [source,console] ---- $ git log --pretty=format:"%h %s" --graph -* 2d3acf9 ignore errors from SIGCHLD on trap +* 2d3acf9 Ignore errors from SIGCHLD on trap * 5e3ee11 Merge branch 'master' of git://github.com/dustin/grit |\ -| * 420eac9 Added a method for getting the current branch. -* | 30e367c timeout code and tests -* | 5a09431 add timeout protection to grit -* | e1193f8 support for heads with slashes in them +| * 420eac9 Add method for getting the current branch +* | 30e367c Timeout code and tests +* | 5a09431 Add timeout protection to grit +* | e1193f8 Support for heads with slashes in them |/ -* d6016bc require time for xmlschema +* d6016bc Require time for xmlschema * 11d191e Merge branch 'defunkt' into local ---- -This type of output will become more interesting as we go through branching and merging in the next chapter. +مادامی که وارد فصل بعدی که درباره برنچ‌ها و مرج ست این نوع خروجی بیشتر مورد پسند واقع خواهد شد. -Those are only some simple output-formatting options to `git log` -- there are many more. -<> lists the options we've covered so far, as well as some other common formatting options that may be useful, along with how they change the output of the log command. +آنها تنها چند آپشن برای خروجی با فرمت متفاوت هستند که در دستور `git log` مورد استفاده قرار می‌گیرد -- بیشتر از اینها آپشن دارد. +<> لیست‌های آپشن‌ها که بعداً درمورد آن هم می‌گوییم،‌ همانطور که دیگر فرمت آپشن‌های معمول را که برایتان مفید بود با توجه به اینکه +چطور خروجی دستور `log` را تغییر می‌دهند گفتیم. [[log_options]] -.Common options to `git log` +.آپشن‌های معمول دستور `git log` [cols="1,4",options="header"] |================================ -| Option | Description -| `-p` | Show the patch introduced with each commit. +| آپشن‌ها | توضیحات +| `-p` | Show the patch introduced with each commit.: | `--stat` | Show statistics for files modified in each commit. | `--shortstat` | Display only the changed/insertions/deletions line from the --stat command. | `--name-only` | Show the list of files modified after the commit information. @@ -224,50 +234,54 @@ Those are only some simple output-formatting options to `git log` -- there are m | `--oneline` | Shorthand for `--pretty=oneline --abbrev-commit` used together. |================================ -==== Limiting Log Output +==== محدود کردن خروجی لاگ -In addition to output-formatting options, `git log` takes a number of useful limiting options -- that is, options that let you show only a subset of commits. -You've seen one such option already -- the `-2` option, which displays only the last two commits. -In fact, you can do `-`, where `n` is any integer to show the last `n` commits. -In reality, you're unlikely to use that often, because Git by default pipes all output through a pager so you see only one page of log output at a time. +علاوه‌بر انواع آپشن‌های فرمت‌ خروجی، `git log` چندین آپشن‌های محدود کننده مفیدی را قبول می‌کند؛ این آپشن‌ها به شما این اجازه را می‌دهند که یک زیرمجموعه از کامیت‌ها را ببینید. +کمی قبل‌تر یکی از این دستورات را دیده بودید -- اگه به خاطر داشته باشید آپشن `2-` که تنها دو کامیت آخر را نمایش می‌داد. +در حقیقت شما می‌توانید این دستور `-` که `n` یک عدد برای نمایش `n` کامیت آخر. -However, the time-limiting options such as `--since` and `--until` are very useful. -For example, this command gets the list of commits made in the last two weeks: +در واقعیت شما معمولاً از دستور استفاده نمی‌کنید چرا که خود گیت به صورت پیش‌فرض همه‌ٔخروجی‌ها را صفحه‌بندی می‌کند که شما فقط یک صفحه خروجی لاگ +را در لحظه می‌بینید در حالی لاگ لیست بلند‌ بالایی است. +با این حال، آپشن‌های محدود کردن زمان مانند `since--` و `until--` بسیار مورد استفاده و مفید هستند. +-- برای مثال، این دستور لیست کامیت‌های ساخته شده در دو هفته‌ی گذشته را نشان می‌دهد. [source,console] ---- $ git log --since=2.weeks ---- -This command works with lots of formats -- you can specify a specific date like `"2008-01-15"`, or a relative date such as `"2 years 1 day 3 minutes ago"`. +این دستور با انواع زیادی از فرمت‌ها کار می‌کند -- شما می‌توانید یک تاریخ معیین مانند `"2008-01-15"` یا +یک تاریخ نسبی مانند `"2years 3days 1minutes"` برایش تعیین کنید. -You can also filter the list to commits that match some search criteria. -The `--author` option allows you to filter on a specific author, and the `--grep` option lets you search for keywords in the commit messages. +همچنین این امکان را دارید که لیست کامیت‌ها را با الگوهای جست‌وجو فیلتر کنید و فقط یافته‌های مطابق با الگو را ببینید. +آپشن `author--` این اجازه را به شما می‌دهد که کامیت‌های یک نویسنده و آپشن `grep--` به شما این امکان را می‌دهد +کلمه کلیدی مورد نظر خودتون در بین پیام‌های کامیت‌ها جست‌وجو کنید. [NOTE] ==== -You can specify more than one instance of both the `--author` and `--grep` search criteria, which -will limit the commit output to commits that match _any_ of the `--author` patterns and _any_ -of the `--grep` patterns; however, adding the `--all-match` option further limits the output to -just those commits that match _all_ `--grep` patterns. +می‌توانید بیش از یک نمونه از هر دو آپشن‌های `author--` و `grep--` برای معیار جست‌وجو تعیین کنید، که محدودیت خروجی وجود داشته باشد +که بر اساس کامیت‌هایی که دارای هر نوع الگو مطابق با آپشن `author--` و هر نوع الگوی مطابق با آپشن `grep--` باشند؛ با این حال +اضافه کردن آپشن `all-match--` نتایج را مطابق با الگوهای `all-match--` محدود میکند. ==== -Another really helpful filter is the `-S` option (colloquially referred to as Git's ``pickaxe'' option), which takes a string and shows only those commits that changed the number of occurrences of that string. -For instance, if you wanted to find the last commit that added or removed a reference to a specific function, you could call: +یکی دیگر از فیلترها مفید استفاده آپشن `S-` است(به طور محاوره‌ای به آن آپشن `pickaxe` گیت گفته می‌شود.)،که یک رشته به عنوان ورودی می‌گیرد +و فقط کامیت‌هایی را نشان داده می‌شود که بیشترین وقوع آن رشته در کامیت‌ها باشد. +برای نمونه، اگر شما بخواهید که آخرین کامیتی که حذف یا اضافه یک رفرنس به یک تابع مشخص باشد پیدا کنید میتوانید اینطوری فراخوانی کنید: [source,console] ---- $ git log -S function_name ---- -The last really useful option to pass to `git log` as a filter is a path. -If you specify a directory or file name, you can limit the log output to commits that introduced a change to those files. -This is always the last option and is generally preceded by double dashes (`--`) to separate the paths from the options. +آخرین آپشن مفید مورد استفاده در دستور `git log` به عنوان یک فیلتر می‌توان استفاده کرد آدرس(path) هست. +اگر شما یک پوشه یا نام یک فایل را مشخص کنید، می‌توانید محدودیت خروجی لاگ فایل را بر اساس کامیت‌هایی باشد +که تغییر آن فایل‌ها را معرفی می‌کند. +این آپشن همیشه اخرین آپشن است و به صورت کلی با دو خط تیره (`--`) برای جدا سازی آدرس از آپشن استفاده می‌شود. -In <> we'll list these and a few other common options for your reference. +در بخش <> ما به عنوان رفرنس شما بخشی کمی از آپشن‌های معمول را برای شما لیست خواهیم کرد. [[limit_options]] -.Options to limit the output of `git log` +.آپشن‌های مختلف برای خروجی `git log` [cols="2,4",options="header"] |================================ | Option | Description @@ -280,11 +294,13 @@ In <> we'll list these and a few other common options for your re | `-S` | Only show commits adding or removing code matching the string |================================ -For example, if you want to see which commits modifying test files in the Git source code history were committed by Junio Hamano in the month of October 2008 and are not merge commits, you can run something like this:(((log filtering))) +به عنوان مثال، می‌خواهیم کامیت‌های اصلاحیات فایل‌های تست در تاریخچه سورس کد گیت که توسط _Junio Hamano_ در تاریخ October 2008 +و مرج کامیت نیستند را ببینیم. +شما می‌توانید با اجرای دستوری مانند دستور پایین چنین نتیجه‌آی را ببینید. [source,console] ---- -$ git log --pretty="%h - %s" --author=gitster --since="2008-10-01" \ +$ git log --pretty="%h - %s" --author='Junio C Hamano' --since="2008-10-01" \ --before="2008-11-01" --no-merges -- t/ 5610e3b - Fix testcase failure when extended attributes are in use acd3b9e - Enhance hold_lock_file_for_{update,append}() API @@ -294,11 +310,12 @@ d1a43f2 - reset --hard/read-tree --reset -u: remove unmerged new paths b0ad11e - pull: allow "git pull origin $something:$current_branch" into an unborn branch ---- -Of the nearly 40,000 commits in the Git source code history, this command shows the 6 that match those criteria. +از ۴۰،۰۰۰ هزار کامیت در تاریخچه سورس کد گیت، این دستور ۶ مورد مطابق الگوهای مورد نظر را نشان داد. [TIP] -.Preventing the display of merge commits +.جلوگیری از نمایش مرج کامیت‌ها ==== -Depending on the workflow used in your repository, it's possible that a sizable percentage of the commits in your log history are just merge commits, which typically aren't very informative. -To prevent the display of merge commits cluttering up your log history, simply add the log option `--no-merges`. +بسته به وضعیت روند کاری مورد استفاده در مخزن شما، این امکان وجود دارد که درصد قابل توجهی از کامیت‌ها فقط مرج کامیت باشند واقعاً نیاز +به نمایش آنها نیست. +برای جلوگیری از نمایش مرج کامیت‌ها به سادگی یک آپشن، `--no-merges` را به دستور اضافه کنید تا مرج کامیت‌ها را نمایش ندهد. ==== diff --git a/book/03-git-branching/1-git-branching.asc b/book/03-git-branching/1-git-branching.asc deleted file mode 100644 index 060666239..000000000 --- a/book/03-git-branching/1-git-branching.asc +++ /dev/null @@ -1,32 +0,0 @@ -[[_git_branching]] -== شاخه سازی در گیت - -(((branches))) -تقریبا همه ی VCS ها به شکلی شاخه سازی را دارند. - شاخه سازی به معنی انشعاب از خط اصلی توسعه و ادامه ی کار در مسیر دیگر بدون از دست دادن خط اصلی است. - در بسیاری از VCS ها این کار تا اندازه ای یک فرآیند پر هزینه است. اغلب نیاز به رونوشت گیری از کل پوشه ی فایلهایست که این کا در پروژه های بزرگ زمان زیادی می گیرد. - -برخی، مدل شاخه سازی گیت را یک "ویژگی منحصر به فرد" میدانند و به راستی این ویژگی، برجسته شدن گیت در جوامع VCS را در پی داشته است. -چرا این ویژگی چنین برجسته است؟ -روش شاخه سازی در گیت بسیار چست و چابک است. عملیات مربوط به شاخه سازی تقریبا آنی و بی درنگ است. انتقال بین شاخه ها و پیش روی در شاخه و برگشت به شاخه ی قبل، معمولا به همان اندازه بسیار سریع است. -بر خلاف دیگر VCSها، گیت جریان هایی از کار که شاخه سازی و ادغام در آن است را بسیار پیشنهاد میدهد و به آن ترغیب می کند. حتی چند بار شاخه سازی و ادغام در روز. -فهم درست و مهار کافی در این ویژگی، به شما ابزار بسیار قدرمتد و یکتایی را می دهد که با آن می توانید شیوه توسعه و کد نویسیتان را به کلی تغییر دهید. - -include::sections/nutshell.asc[] - -include::sections/basic-branching-and-merging.asc[] - -include::sections/branch-management.asc[] - -include::sections/workflows.asc[] - -include::sections/remote-branches.asc[] - -include::sections/rebasing.asc[] - -=== Summary - -We've covered basic branching and merging in Git. -You should feel comfortable creating and switching to new branches, switching between branches and merging local branches together. -You should also be able to share your branches by pushing them to a shared server, working with others on shared branches and rebasing your branches before they are shared. -Next, we'll cover what you'll need to run your own Git repository-hosting server. diff --git a/book/03-git-branching/sections/basic-branching-and-merging.asc b/book/03-git-branching/sections/basic-branching-and-merging.asc index b717a3324..b1dd3573e 100644 --- a/book/03-git-branching/sections/basic-branching-and-merging.asc +++ b/book/03-git-branching/sections/basic-branching-and-merging.asc @@ -1,31 +1,31 @@ -=== Basic Branching and Merging +=== مقدمات برنچ‌سازی و مرج‌کردن -Let's go through a simple example of branching and merging with a workflow that you might use in the real world. -You'll follow these steps: +حال بیایید با هم به یک نمونه ساده از مرج‌کردن و برنچ‌سازی با یک روند کاری که احتمالاً در دنیای واقعی از آن استفاده خواهید کرد بپردازیم. +شما این مراحل را دنبال خواهید کرد: -. Do some work on a website. -. Create a branch for a new story you're working on. -. Do some work in that branch. +. کمی کار کردن روی یک وبسایت. +. ساختن یک برنچ جدید برای یک یوزراستوری جدید که روی آن کار می‌کنید. +. کمی پرداختن به کارهای آن برنچ -At this stage, you'll receive a call that another issue is critical and you need a hotfix. -You'll do the following: +در این وهله شما تماسی از تماسی دریافت می‌کنید که یک مورد بحرانی پیش آمده و باید یک راه حل سریع (هات‌فیکس) برای آن آماده کنید. +شما کارهای زیر را انجام خواهید داد: -. Switch to your production branch. -. Create a branch to add the hotfix. -. After it's tested, merge the hotfix branch, and push to production. -. Switch back to your original story and continue working. +. تعویض برنچ به برنچ پروداکشن (برنچ احتمالی که نسخه‌های با ثبات و کاری را در خود نگه می‌دارد) +. ساختن یک برنچ برای اضافه کردن هات‌فیکس به پروژه +. پس از اینکه تست شد برنچ هات‌فیکس را مرج می‌کنید و تغییرات را به برنچ پروداکشن پوش می‌کنید. +. به یوزراستوری قبلی که روی آن کار می‌کردید باز می‌گردید و ادامهٔ کارتان را انجام می‌دهید. [[_basic_branching]] -==== Basic Branching +==== مقدمات برنچ‌سازی (((branches, basic workflow))) -First, let's say you're working on your project and have a couple of commits already on the `master` branch. +در ابتدا فرض کنیم که شما روی پروژه‌ای کار می‌کنید و از قبل تعدادی کامیت روی برنچ `master` دارید. -.A simple commit history +.یک تاریخچهٔ کامیت ساده image::images/basic-branching-1.png[A simple commit history.] -You've decided that you're going to work on issue #53 in whatever issue-tracking system your company uses. -To create a new branch and switch to it at the same time, you can run the `git checkout` command with the `-b` switch: +شما تصمیم گرفته‌اید که روی ایشو #53 در سیستم پیگیری-مشکلی (Issue-Tracking System) که کمپانی شما از آن استفاده می‌کند کار کنید. +برای ساختن یک برنچ جدید و تعویض برنچ در آن واحد می‌توانید دستور `git checkout` را با کلید `-b` اجرا کنید: [source,console] ---- @@ -33,7 +33,7 @@ $ git checkout -b iss53 Switched to a new branch "iss53" ---- -This is shorthand for: +این دستور جایگزین کوتاهی برای خطوط زیر است: [source,console] ---- @@ -41,29 +41,31 @@ $ git branch iss53 $ git checkout iss53 ---- -.Creating a new branch pointer +.ساختن یک نشانگر برنچ جدید image::images/basic-branching-2.png[Creating a new branch pointer.] -You work on your website and do some commits. -Doing so moves the `iss53` branch forward, because you have it checked out (that is, your `HEAD` is pointing to it): +شما روی سایت خود کار می‌کنید و چند کامیت می‌کنید. +انجام چنین کاری برنچ `iss53` را به جلو هدایت می‌کند، به این دلیل که شما آنرا چک‌اوت کرده‌اید (یعنی `HEAD` شما به آن اشاره دارد): [source,console] ---- $ vim index.html -$ git commit -a -m 'added a new footer [issue 53]' +$ git commit -a -m 'Create new footer [issue 53]' ---- -.The `iss53` branch has moved forward with your work +.برنچ `iss53` با کار شما به جلو رفته است image::images/basic-branching-3.png[The `iss53` branch has moved forward with your work.] -Now you get the call that there is an issue with the website, and you need to fix it immediately. -With Git, you don't have to deploy your fix along with the `iss53` changes you've made, and you don't have to put a lot of effort into reverting those changes before you can work on applying your fix to what is in production. -All you have to do is switch back to your `master` branch. +حال تماسی به شما می‌گوید که مشکلی در وبسایت هست و شما باید درجا آنرا درست کنید. +با گیت، شما مجبور نمی‌شوید که فیکس خود را با تغییراتی که در `iss53` داده‌اید ارائه کنید و مجبور نیستید کلی تلاش کنید تا تغییرات را به پروداکشن بازگردانی +کنید تا بتوانید فیکس را توسعه دهید. +تمام کاری که نیاز است انجام دهید این است که به برنچ `master` بازگردید. -However, before you do that, note that if your working directory or staging area has uncommitted changes that conflict with the branch you're checking out, Git won't let you switch branches. -It's best to have a clean working state when you switch branches. -There are ways to get around this (namely, stashing and commit amending) that we'll cover later on, in <<_git_stashing>>. -For now, let's assume you've committed all your changes, so you can switch back to your `master` branch: +اگرچه قبل از اینکه آن کار را انجام دهید باید دقت کنید که اگر پوشه کاری یا استیج شما تغییرات کامیت‌نشده‌ای دارد که باعث ایجاد تداخل (Conflict) در +برنچی که می‌خواهید به آن چک‌اوت کنید می‌شود، گیت به شما اجازهٔ تعویض برنچ نمی‌دهد. +همیشه بهتر است قبل از تعویض برنچ پوشه کاری را تمیز کنید. +راه‌های متفاوتی برای انجام این تمیزکاری وجود دارد (من جمله استش (Stash) و اصلاح (Amend) کامیت) که در <> به آن خواهیم پرداخت. +فعلاً بیاید فرض کنیم که تغییرات را همه کامیت کرده‌اید و می‌توانید به برنچ `master` خودت انتقال پیدا کنید: [source,console] ---- @@ -71,28 +73,29 @@ $ git checkout master Switched to branch 'master' ---- -At this point, your project working directory is exactly the way it was before you started working on issue #53, and you can concentrate on your hotfix. -This is an important point to remember: when you switch branches, Git resets your working directory to look like it did the last time you committed on that branch. -It adds, removes, and modifies files automatically to make sure your working copy is what the branch looked like on your last commit to it. +تا اینجای کار پوشه کاری پروژهٔ شما دقیقاً مانند قبل از زمانی است که شروع به کار روی ایشو #53 کردید و می‌توانید روی هات‌فیکس خود تمرکز کنید. +این نکته مهمی برای به خاطر سپردن است: هنگامی که برنچ را تعویض می‌کنید، گیت پوشه کاری شما را بازنشانی می‌کند تا دقیقاً مشابه زمانی شود که اولین بار کامیت روی +آن برنچ را ساختید. +گیت فایل‌ها را به طور خودکار فایل‌ها را کم زیاد یا ویرایش می‌کند تا مطمئن شود که کپی فعال شما عیناً مطابق زمانی است که آخرین کامیت را روی برنچ ثبت کرده‌اید. -Next, you have a hotfix to make. -Let's create a `hotfix` branch on which to work until it's completed: +در ادامه شما باید به هات‌فیکس خود بپردازید. +بیاید یک برنچ `hotfix` بسازیم و تا زمان تمام شدنش روی آن کار کنیم: [source,console] ---- $ git checkout -b hotfix Switched to a new branch 'hotfix' $ vim index.html -$ git commit -a -m 'fixed the broken email address' -[hotfix 1fb7853] fixed the broken email address +$ git commit -a -m 'Fix broken email address' +[hotfix 1fb7853] Fix broken email address 1 file changed, 2 insertions(+) ---- -.Hotfix branch based on `master` +.برنچ هات‌فیکس در ادامهٔ `master` image::images/basic-branching-4.png[Hotfix branch based on `master`.] -You can run your tests, make sure the hotfix is what you want, and finally merge the `hotfix` branch back into your `master` branch to deploy to production. -You do this with the `git merge` command:(((git commands, merge))) +شما می‌توانید تست‌های خود را بگیرید، از اینکه هات‌فیکس آنگونه که شما می‌خواهید هست اطمینان حاصل کنید و در آخر برنچ `hotfix` را با برنچ `master` مرج کنید تا روی +محیط پروداکشن پیاده‌سازی کنید. شما می‌توانید این کار را با دستور `git merge` انجام دهید:(((git commands, merge))) [source,console] ---- @@ -104,18 +107,20 @@ Fast-forward 1 file changed, 2 insertions(+) ---- -You'll notice the phrase ``fast-forward'' in that merge. -Because the commit `C4` pointed to by the branch `hotfix` you merged in was directly ahead of the commit `C2` you're on, Git simply moves the pointer forward. -To phrase that another way, when you try to merge one commit with a commit that can be reached by following the first commit's history, Git simplifies things by moving the pointer forward because there is no divergent work to merge together -- this is called a ``fast-forward.'' +شما متوجه عبارت ``fast-forward'' در آن مرج می‌شوید. +به این دلیل که کامیت `C4` توسط برنچ `hotfix` مورد اشاره قرار گرفته که دقیقاً جلوی کامیت `C2` است که شما هم روی آن کار می‌کنید. +به جای انجام کار اضافی گیت به سادگی نشانگر را به جلو هل می‌دهد. +به بیان دیگر وقتی سعی می‌کنید یک کامیت را با کایمت دیگری که می‌توان از طریق یپمودن مسیر کامیت اول به آن رسید، مرج کنید، گیت نشانگر را به جلو می‌کشد +چون دوشاخگی در مسیر وجود ندارد که گیت بخواهد آنرا ادغام کند -- به این کار ``fast-forward'' (فست-فوروارد) می‌گویند. -Your change is now in the snapshot of the commit pointed to by the `master` branch, and you can deploy the fix. +اکنون تغییرات شما در اسنپ‌شات کامیتی که برنچ `master` به آن اشاره می‌کند موجود است و شما می‌توانید فیکس خود را ارائه کنید. -.`master` is fast-forwarded to `hotfix` +.`master` به `hotfix` فست-فوروارد شد. image::images/basic-branching-5.png[`master` is fast-forwarded to `hotfix`.] -After your super-important fix is deployed, you're ready to switch back to the work you were doing before you were interrupted. -However, first you'll delete the `hotfix` branch, because you no longer need it -- the `master` branch points at the same place. -You can delete it with the `-d` option to `git branch`: +پس از اینکه فیکس فوق مهمتان ارائه شد، آماده‌اید تا به کاری که پیش از اینکه به شما اطلاع داده شود بازگردید. +هرچند ابتدا شما برنچ `hotfix` را پاک خواهید کرد، چرا که دیگر آنرا احتیاج ندارید -- برنچ `master` به همانجا اشاره دارد. +شما می‌توانید با آپشن `-d` دستور `git branch` آنرا پاک کنید: [source,console] ---- @@ -123,31 +128,32 @@ $ git branch -d hotfix Deleted branch hotfix (3a0874c). ---- -Now you can switch back to your work-in-progress branch on issue #53 and continue working on it. +حال می‌توانید به برنچ در حال تکمیل شدن قبلی که دربارهٔ ایشو #53 بود بازگردید و روی آن کار کنید: [source,console] ---- $ git checkout iss53 Switched to branch "iss53" $ vim index.html -$ git commit -a -m 'finished the new footer [issue 53]' -[iss53 ad82d7a] finished the new footer [issue 53] +$ git commit -a -m 'Finish the new footer [issue 53]' +[iss53 ad82d7a] Finish the new footer [issue 53] 1 file changed, 1 insertion(+) ---- -.Work continues on `iss53` +.کار روی `iss53` ادامه پیدا خواهد کرد image::images/basic-branching-6.png[Work continues on `iss53`.] -It's worth noting here that the work you did in your `hotfix` branch is not contained in the files in your `iss53` branch. -If you need to pull it in, you can merge your `master` branch into your `iss53` branch by running `git merge master`, or you can wait to integrate those changes until you decide to pull the `iss53` branch back into `master` later. +اهمیتی ندارد که کاری که روی برنچ `hotfix` خود به انجام رسانیده‌اید در فایل‌های برنچ `iss53` موجود نیست. +اگر احتیاج دارید تا آنرا پول کنید، می‌توانید با اجرای `git merge master` برنچ `master` را در برنچ `iss53` مرج کنید؛ یا می‌توانید تا بعدتر صبر کنید، +تا تغییرات را یکپارچه‌سازی کنید تا زمانی که تصمیم به این بگیرید که برنچ `iss53` را به برنچ `master` پول کنید. [[_basic_merging]] -==== Basic Merging +==== مرج‌کردن مقدماتی (((branches, merging)))(((merging))) -Suppose you've decided that your issue #53 work is complete and ready to be merged into your `master` branch. -In order to do that, you'll merge your `iss53` branch into `master`, much like you merged your `hotfix` branch earlier. -All you have to do is check out the branch you wish to merge into and then run the `git merge` command: +فرض کنید به این نتیجه رسیده‌اید که کار روی ایشوی #53 تمام شده و آماده است تا با برنچ `master` مرج شود. +برای اینکه این کار را انجام دهید، شما برنچ `iss53` را درون برنچ `master` می‌ریزید و ادغام می‌کنید؛ بسیار شبیه به قبل، زمانی که برنچ `hotfix` را مرج کردید. +تمام کاری که باید بکنید این است که برنچی که می‌خواهید تغییرات را به آن بریزید و ادغام شود را چک‌اوت کنید و دستور `git merge` را اجرا کنید: [source,console] ---- @@ -159,25 +165,22 @@ index.html | 1 + 1 file changed, 1 insertion(+) ---- -This looks a bit different than the `hotfix` merge you did earlier. -In this case, your development history has diverged from some older point. -Because the commit on the branch you're on isn't a direct ancestor of the branch you're merging in, Git has to do some work. -In this case, Git does a simple three-way merge, using the two snapshots pointed to by the branch tips and the common ancestor of the two. +این بار کمی با مرج `hotfix` که قبلاً انجام داده‌اید تفاوت می‌کند. +در این مورد، تاریخچهٔ توسعهٔ شما از یک نقطه به آنور دوشاخه شده بود. +چرا که کامیتی که روی برنچ کاری شماست، در مسیر مسقتیم برنچی که با آن ادغام می‌شود نیست و گیت باید در این رابطه کاری کند. +در این شرایط گیت یک مرج سه طرفه، با استفاده از دو اسنپ‌شاتی که نوک برنچ‌ها به آنها اشاره می‌کنند و یک والد مشترک از دو برنچ انجام می‌دهد. -.Three snapshots used in a typical merge +.در یک مرج معمولی سه اسنپ‌شات استفاده می‌شود image::images/basic-merging-1.png[Three snapshots used in a typical merge.] -Instead of just moving the branch pointer forward, Git creates a new snapshot that results from this three-way merge and automatically creates a new commit that points to it. -This is referred to as a merge commit, and is special in that it has more than one parent. +به جای جلو بردن پوینتر برنچ‌تان به جلو، گیت یک اسنپ‌شات جدید می‌سازد که حاصل این مرج سه طرفه است و به طور خودکار یک کامیت می‌سازد که به آن اسنپ‌شات اشاره می‌کند. +این کامیت به عنوان یک «مرج کامیت»، نوعی کایمت خاص که بیش از والد دارد، شناخته می‌شود. -.A merge commit +.یک مرج کامیت image::images/basic-merging-2.png[A merge commit.] -It's worth pointing out that Git determines the best common ancestor to use for its merge base; this is different than older tools like CVS or Subversion (before version 1.5), where the developer doing the merge had to figure out the best merge base for themselves. -This makes merging a heck of a lot easier in Git than in these other systems. - -Now that your work is merged in, you have no further need for the `iss53` branch. -You can close the ticket in your ticket-tracking system, and delete the branch: +توجه کنید که کار شما ادغام شده است و شما دیگر نیازی به برنچ `iss53` ندارید. +شما می‌توانید ایشو را در سیستم پیگیری-مشکلتان ببندید و برنچ را پاک کنید: [source,console] ---- @@ -185,12 +188,12 @@ $ git branch -d iss53 ---- [[_basic_merge_conflicts]] -==== Basic Merge Conflicts +==== تداخلات مرج پایه (((merging, conflicts))) -Occasionally, this process doesn't go smoothly. -If you changed the same part of the same file differently in the two branches you're merging together, Git won't be able to merge them cleanly. -If your fix for issue #53 modified the same part of a file as the `hotfix` branch, you'll get a merge conflict that looks something like this: +هر از گاهی این فرآیند به این آسانی انجام نمی‌پذیرد. +اگر دو تغییر متفاوت در یک بخش از یک فایل در دو برنچی که در حال ادغامشان هستید ایجاد کردید، گیت قادر نخواهد بود که بی‌نقص آنها را مرج کند. +اگر فیکس ایشو #53 شما همان بخشی را از یک فایل ویرایش کرده که در برنچ `hotfix` هم ویرایش شده، شما یک تداخل (Conflict) مرج خواهید دید که چیزی شبیه زیر خواهد بود: [source,console] ---- @@ -200,9 +203,9 @@ CONFLICT (content): Merge conflict in index.html Automatic merge failed; fix conflicts and then commit the result. ---- -Git hasn't automatically created a new merge commit. -It has paused the process while you resolve the conflict. -If you want to see which files are unmerged at any point after a merge conflict, you can run `git status`: +گیت به طور خودکار یک مرج کامیت جدید نساخته است. +فرآیند را متوقف کرده است تا شما تداخل را حل کنید. +هرگاه می‌خواهید ببینید که چه فایل‌هایی در یک تداخل مرج، مرج‌نشده باقی مانده‌اند، می‌توانید دستور `git status` را اجرا کنید: [source,console] ---- @@ -219,9 +222,9 @@ Unmerged paths: no changes added to commit (use "git add" and/or "git commit -a") ---- -Anything that has merge conflicts and hasn't been resolved is listed as unmerged. -Git adds standard conflict-resolution markers to the files that have conflicts, so you can open them manually and resolve those conflicts. -Your file contains a section that looks something like this: +هر چیزی که تداخل دارد و حل نشده مانده باشد به عنوان «مرج‌نشده» (_Unmerged_) لیست می‌شود. +گیت چند نشاندهٔ استاندارد حل-تداخل را به فایل‌هایی که در تداخل پیدا کرده‌اند اضافه می‌کند تا شما بتوانید آن‌ها را باز کرده و حل کنید. +فایل شما بخشی خواهد داشت که شبیه زیر خواهد بود: [source,html] ---- @@ -234,9 +237,10 @@ Your file contains a section that looks something like this: >>>>>>> iss53:index.html ---- -This means the version in `HEAD` (your `master` branch, because that was what you had checked out when you ran your merge command) is the top part of that block (everything above the `=======`), while the version in your `iss53` branch looks like everything in the bottom part. -In order to resolve the conflict, you have to either choose one side or the other or merge the contents yourself. -For instance, you might resolve this conflict by replacing the entire block with this: +این بدان معناست که نسخه‌ای که در `HEAD` وجود دارد (برنچ `master` شما، چرا که این برنچ جایی است که آخرین بار پیش از اینکه دستور مرج را اجرا کنید چک‌اوت کردید) بخش بالایی +است (هر چیزی که بالای `=======` قرار دارد)، در حالی که نسخه‌ای که در برنچ `iss53` است مشابه نوشته‌های بخش زیرین است. +برای حل تداخل، شما می‌توانید یکی از دو طرف را انتخاب کرده یا محتوا را خودتان ادغام کنید. +به طور مثال ممکن است شما کل آن بلوک کد را با چنین محتوایی جایگزین کنید: [source,html] ---- @@ -245,11 +249,12 @@ please contact us at email.support@github.com ---- -This resolution has a little of each section, and the `<<<<<<<`, `=======`, and `>>>>>>>` lines have been completely removed. -After you've resolved each of these sections in each conflicted file, run `git add` on each file to mark it as resolved. -Staging the file marks it as resolved in Git. +این راه حل کمی از هر بخش را در خود دارد و نشانه‌های `>>>>>>>`، `=======` و `<<<<<<<` هم کاملاً پاک شده‌اند. +بعد از اینکه هر تکه از فایل متداخل را ویرایش کردید، `git add` را روی هر فایل اجرا کنید تا آنرا به عنوان حل شده علامت‌گذاری کنید. +استیج‌کردن فایل آنرا به عنوان حل شده در گیت علامت‌گذاری می‌کند. -If you want to use a graphical tool to resolve these issues, you can run `git mergetool`, which fires up an appropriate visual merge tool and walks you through the conflicts:(((git commands, mergetool))) +اگر می‌خواهید تا از ابزاری گرافیکی برای حل این مسائل استفاده کنید، می‌توانید `git mergetool` را اجرا کنید که +یک ابزار مرج بصری مناسب اجار می‌کند و شما را در تداخل‌ها همراهی می‌کند:(((git commands, mergetool))) [source,console] ---- @@ -268,17 +273,18 @@ Normal merge conflict for 'index.html': Hit return to start merge resolution tool (opendiff): ---- -If you want to use a merge tool other than the default (Git chose `opendiff` in this case because the command was run on a Mac), you can see all the supported tools listed at the top after ``one of the following tools.'' -Just type the name of the tool you'd rather use. +اگر می‌خواهید از ابزار مرجی به جز ابزار پیش‌فرض استفاده کنید (در این مورد گیت `opendiff` را انتخاب کرده چرا که دستور روی یک مک اجرا شده)، +می‌توانید لیست تمام ابزارهای پشتیبانی شده را در ابتدا پس از ``one of the following tools'' مشاهده کنید. +کافیست نام ابزاری که ترجیح می‌دهید استفاده کنید وارد کنید: [NOTE] ==== -If you need more advanced tools for resolving tricky merge conflicts, we cover more on merging in <<_advanced_merging>>. +اگر به ابزار پیشرفته‌تری برای حل تداخل‌های خاص دارید، ما به بحث مرج‌کردن در <> بیشتر می‌پردازیم. ==== -After you exit the merge tool, Git asks you if the merge was successful. -If you tell the script that it was, it stages the file to mark it as resolved for you. -You can run `git status` again to verify that all conflicts have been resolved: +پس از اینکه ابزار مرج را بستید، گیت از شما می‌پرسد که آیا مرج موفقیت‌آمیز بود. +اگر به اسکریپت بگویید که موفقیت‌آمیز بود، فایل‌ها را استیج می‌کند تا آنها را برای شما به عنوان حل شده علامت زده باشد. +شما می‌توانید با اجرای دوبارهٔ `git status` تصدیق کنید که تمام تداخلات حل شده‌اند: [source,console] ---- @@ -292,8 +298,8 @@ Changes to be committed: modified: index.html ---- -If you're happy with that, and you verify that everything that had conflicts has been staged, you can type `git commit` to finalize the merge commit. -The commit message by default looks something like this: +اگر از این خروجی راضی هستید و تصدیق می‌کنید که همه چیز استیج شده است می‌توانید `git commit` را تایپ کنید تا مرج کامیت را ثبت کنید. +پیغام پیش‌فرض کامیت چیزی شبیه زیر خواهد بود: [source,console] ---- @@ -318,4 +324,5 @@ Conflicts: # ---- -If you think it would be helpful to others looking at this merge in the future, you can modify this commit message with details about how you resolved the merge and explain why you did the changes you made if these are not obvious. +اگر فکر می‌کنید که برای دیگرانی که در آینده به این مرج کامیت نگاه می‌کنند مفیدتر است، می‌توانید این پیغام را با جزئیاتی از اینکه چگونه این تداخل +را حل کرده‌اید باز نویسی کنید و اگر واضح نیست، توضیح دهید که چه تغییراتی اعمال کرده‌اید. diff --git a/book/03-git-branching/sections/branch-management.asc b/book/03-git-branching/sections/branch-management.asc index 3b384babb..33ad7c763 100644 --- a/book/03-git-branching/sections/branch-management.asc +++ b/book/03-git-branching/sections/branch-management.asc @@ -1,11 +1,11 @@ [[_branch_management]] -=== Branch Management +=== مدیریت برنچ (((branches, managing))) -Now that you've created, merged, and deleted some branches, let's look at some branch-management tools that will come in handy when you begin using branches all the time. +حال که چند برنچ را ساخته‌اید، مرج و پاک کرده‌اید، بیاید نگاهی به چند ابزار مدیریت برنچ بیندازیم که وقتی به شروع به استفادهٔ مادام از برنچ‌ها کردید به کارتان می‌آید. -The `git branch` command does more than just create and delete branches.(((git commands, branch))) -If you run it with no arguments, you get a simple listing of your current branches: +دستور `git branch` بیشتر از ساختن و نابود کردن برنچ‌ها به کار می‌آید. +اگر بدون هیچ آرگومانی آنرا اجرا کنید، یک لیست ساده از برنچ‌های حاضر پروژه را به شما نمایش می‌دهد: [source,console] ---- @@ -15,20 +15,20 @@ $ git branch testing ---- -Notice the `*` character that prefixes the `master` branch: it indicates the branch that you currently have checked out (i.e., the branch that `HEAD` points to). -This means that if you commit at this point, the `master` branch will be moved forward with your new work. -To see the last commit on each branch, you can run `git branch -v`: +به علامت `*` که پیش از برنچ `master` آمده توجه کنید: این علامت نشان‌دهندهٔ برنچی است که چک‌اوت کرده‌اید (به بیان دیگر برنچی که `HEAD` به آن اشاره دارد). +این بدان معناست که اگر الآن کامیتی بگیرید، برنچ `master` با کار جدید شما به جلو می‌رود. +برای دیدن آخرین کامیت هر برنچ می‌توانید `git branch -v` را اجرا کنید: [source,console] ---- $ git branch -v - iss53 93b412c fix javascript issue + iss53 93b412c Fix javascript issue * master 7a98805 Merge branch 'iss53' - testing 782fd34 add scott to the author list in the readmes + testing 782fd34 Add scott to the author list in the readme ---- -The useful `--merged` and `--no-merged` options can filter this list to branches that you have or have not yet merged into the branch you're currently on. -To see which branches are already merged into the branch you're on, you can run `git branch --merged`: +آپشن‌های پرکاربرد `--merged` و `--no-merged` می‌توانند این لیست را به برنچ‌هایی که هنوز به برنچ حاضر مرج‌کرده یا نکرده‌اید محدود کند. +برای اطلاع از اینکه چه برنچی با برنچ حاضر مرج‌شده است می‌توانید دستور `git branch --merged` را اجرا کنید: [source,console] ---- @@ -37,10 +37,11 @@ $ git branch --merged * master ---- -Because you already merged in `iss53` earlier, you see it in your list. -Branches on this list without the `*` in front of them are generally fine to delete with `git branch -d`; you've already incorporated their work into another branch, so you're not going to lose anything. +به این دلیل که شما سابقاً با `iss53` مرج شده‌اید آنرا در این لیست مشاهده می‌کنید. +برنچ‌هایی که در این لیست در مقابلشان `*` ندارد، غالباً می‌توانند بی‌مشکل با `git branch -d` پاک شوند. +شما قبل‌تر آنها را درون برنچی دیگر ریخته‌اید پس با پاک کردنشان چیزی از دست نخواهید داد. -To see all the branches that contain work you haven't yet merged in, you can run `git branch --no-merged`: +برای مشاهده تمام برنچ‌هایی که شامل کارهایی هستند که هنوز مرج‌شان نکرده‌اید، می‌توانید `git branch --no-merged` را اجرا کنید: [source,console] ---- @@ -48,8 +49,8 @@ $ git branch --no-merged testing ---- -This shows your other branch. -Because it contains work that isn't merged in yet, trying to delete it with `git branch -d` will fail: +این دستور برنچ دیگر شما را نشان می‌دهد. +به این دلیل که شامل کاری است که هنوز مرج نکرده‌اید، تلاش برای پاک کردنش با `git branch -d` شکست خواهد خورد: [source,console] ---- @@ -58,13 +59,14 @@ error: The branch 'testing' is not fully merged. If you are sure you want to delete it, run 'git branch -D testing'. ---- -If you really do want to delete the branch and lose that work, you can force it with `-D`, as the helpful message points out. +اگر واقعاً می‌خواهیدی که آنرا پاک کنید و کار خود را از دست بدهید می‌توانید با `-D` آنرا به گیت تحمیل کنید، همانطور که در پیغام کمکی بالا به آن اشاره شده است. [TIP] ==== -The options described above, `--merged` and `--no-merged` will, if not given a commit or branch name as an argument, show you what is, respectively, merged or not merged into your _current_ branch. +اگر نام برنچ یا کامیتی به عنوان یک آرگومان به آپشن‌های مشروح بالا داده نشود، `--merged` و `--no-merged` به ترتیب به شما خروجی‌هایی را نشان می‌دهند که به نسبت برنچ _حاضر_ مرج‌شده یا مرج‌نشده‌اند. -You can always provide an additional argument to ask about the merge state with respect to some other branch without checking that other branch out first, as in, what is not merged into the `master` branch? +همیشه می‌توانید یک آرگومان اضافه برای درخواست وضعیت مرج حاضر به نسبت برنچی خاص را وارد دستور کنید بدون آنکه بخواهید روی آن برنچ چک‌اوت کنید، +مثلاً بخواهید بدانید چه برنچی با برنچ `master` مرج نشده است. [source,console] ---- $ git checkout testing diff --git a/book/03-git-branching/sections/nutshell.asc b/book/03-git-branching/sections/nutshell.asc index 505556037..d0527670f 100644 --- a/book/03-git-branching/sections/nutshell.asc +++ b/book/03-git-branching/sections/nutshell.asc @@ -1,111 +1,115 @@ [[_git_branches_overview]] -=== Branches in a Nutshell +=== برنچ‌ها در یک کلمه -To really understand the way Git does branching, we need to take a step back and examine how Git stores its data. +برای اینکه به راستی نحوهٔ شاخه‌سازی گیت را درک کنید، باید یک قدم به عقب برگردیم و نحوهٔ ثبت اطلاعات گیت را مطالعه کنیم. -As you may remember from <<_getting_started>>, Git doesn't store data as a series of changesets or differences, but instead as a series of snapshots. +همانطور که از <> به یاد دارید،‌گیت داده‌ها را به عنوان دسته‌ای از تغییرات یا تفاوت‌هایی بین فایل‌ها ذخیره نمی‌کند؛ +بلکه اطلاعات را بر به عنوان مجموعه‌ای از _اسنپ‌شات‌ها_ ذخیره می‌کند. -When you make a commit, Git stores a commit object that contains a pointer to the snapshot of the content you staged. -This object also contains the author's name and email, the message that you typed, and pointers to the commit or commits that directly came before this commit (its parent or parents): zero parents for the initial commit, one parent for a normal commit, and multiple parents for a commit that results from a merge of two or more branches. +وقتی یک کامیت می‌سازید، گیت یک آبجکت کامیت که شامل یک نشانگر به اسنپ‌شات دربرگیرندهٔ اطلاعات صحنهٔ شماست را ذخیره می‌کند. +این آبجکت همچنین شامل نام نویسنده و آدرس ایمیل او، پیغامی که وارد کرده‌اید و یک نشانگر به کامیت یا کامیت‌هایی که مستقیماً قبل این کامیت (والد یا والدین) آمده‌اند است. +کامیت اولیه والدی ندارد؛ یک کامیت معمولی یک والد دارد؛ یک کامیت که حاصل مرج یک یا چند برنچ است چند والد دارد. -To visualize this, let's assume that you have a directory containing three files, and you stage them all and commit. -Staging the files computes a checksum for each one (the SHA-1 hash we mentioned in <<_getting_started>>), stores that version of the file in the Git repository (Git refers to them as blobs), and adds that checksum to the staging area: +برای ملموس کردن این موضوع، فرض را بر این بگذاریم که پوشه‌ای حاوی سه فایل داریم و شما همهٔ آنها را استیج و کامیت می‌کنید. +استیج کردن فایل‌های برای هر کدام از آنها یک چک‌سام (هش SHA-1 که در<> ذکر کردیم) محاسبه می‌کند، آن نسخه از فایل را در مخزن گیت ذخیره می‌کند، +(گیت از این فایل‌های با نام _بلاب_ یاد می‌کند) و آن چک‌سام را به استیج اضافه می‌کند: [source,console] ---- $ git add README test.rb LICENSE -$ git commit -m 'The initial commit of my project' +$ git commit -m 'Initial commit' ---- -When you create the commit by running `git commit`, Git checksums each subdirectory (in this case, just the root project directory) and stores those tree objects in the Git repository. -Git then creates a commit object that has the metadata and a pointer to the root project tree so it can re-create that snapshot when needed.(((git commands, commit))) +وقتی کامیتی را با اجرای `git commit` می‌سازید، گیت همهٔ زیرپوشه‌ها (در مثال فقط روت پروژه) را چک‌سام می‌کند و آن‌ها را به عنوان یک آبجکت درخت در مخزن گیت ذخیره می‌کند. +سپس گیت یک کامیت آبجکت که متادیتا و نشانگری که به روت درخت پروژه دارد می‌سازد تا بتواند اسنپ‌شات پروژه را هنگامی که نیاز بود بازسازی کند.(((git commands, commit))) -Your Git repository now contains five objects: one blob for the contents of each of your three files, one tree that lists the contents of the directory and specifies which file names are stored as which blobs, and one commit with the pointer to that root tree and all the commit metadata. +مخزن گیت شما حالا پنج آبجکت دارد: سه _بلاب_ (هر کدام نماینده محتوای یکی از سه فایل هستند)، یک _درخت_ که محتویات پوشه را لیست می‌کند و +تعیین می‌کند که چه فایل نام‌هایی در چه بلاب‌هایی ذخیره شده‌اند و یک _کامیت_ با نشانگری به روت آن درخت و تمام متادیتای خود کامیت. -.A commit and its tree +.یک کامیت و درختش image::images/commit-and-tree.png[A commit and its tree.] -If you make some changes and commit again, the next commit stores a pointer to the commit that came immediately before it. +اگر تغییری ایجاد کنید و دوباره کامیت بگیرید، کامیت بعدی نشانگری را به کامیتی که دقیقاً قبل از آن آمده در خود ذخیره می‌کند. -.Commits and their parents +.کامیت‌ها و والدینشان image::images/commits-and-parents.png[Commits and their parents.] -A branch in Git is simply a lightweight movable pointer to one of these commits. -The default branch name in Git is `master`. -As you start making commits, you're given a `master` branch that points to the last commit you made. -Every time you commit, it moves forward automatically. +یک برنچ گیت یک نشانگر سبک‌وزن قابل انتقال به یکی از این کامیت‌هاست. +نام پیش‌‌فرض برنچ در گیت `master` است. +همچنان که کامیت می‌سازید، یک برنچ `master` برایتان ساخته می‌شود که به آخرین کامیتی که ساخته‌اید اشاره می‌کند. +هر بار که کامیت می‌کنید نشانگر برنچ `master` به طور خودکار به جلو حرکت می‌کند. [NOTE] ==== -The ``master'' branch in Git is not a special branch.(((master))) -It is exactly like any other branch. -The only reason nearly every repository has one is that the `git init` command creates it by default and most people don't bother to change it. +برنچ ``master'' در گیت برنچ خاصی نیست.(((master))) +این برنچ دقیقاً مشابه هر برنچ دیگری است. +تنها دلیلی که تقریباً همهٔ مخزن‌ها یک برنچ با این نام دارند این است که دستور `git init` به طور پیش‌فرض آنرا می‌سازد و بیشتر مردم هم زحمت تغییر این نام را به خود نمی‌دهند. ==== -.A branch and its commit history +.یک برنچ و تاریخچهٔ کامیت‌هایش image::images/branch-and-history.png[A branch and its commit history.] [[_create_new_branch]] -==== Creating a New Branch +==== ساختن یک برنچ جدید (((branches, creating))) -What happens if you create a new branch? -Well, doing so creates a new pointer for you to move around. -Let's say you create a new branch called testing. -You do this with the `git branch` command:(((git commands, branch))) +وقتی یک برنچ جدید می‌سازید چه اتفاقی می‌افتد؟ +انجام این کار یک نشانگر جدید برای شما می‌سازد تا آنرا به این سو و آن سو انتقال دهید. +فرض بر این بگذاریم که می‌خواهید برنچ جدیدی با نام `testing` بسازید. +شما این کار را با دستور `git branch` انجام می‌دهید:(((git commands, branch))) [source,console] ---- $ git branch testing ---- -This creates a new pointer to the same commit you're currently on. +این کار یک نشانگر جدید به کامیتی که روی آن هستید می‌سازد. -.Two branches pointing into the same series of commits +.دو برنچ که به یک دسته از کامیت‌ها اشاره می‌کنند image::images/two-branches.png[Two branches pointing into the same series of commits.] -How does Git know what branch you're currently on? -It keeps a special pointer called `HEAD`. -Note that this is a lot different than the concept of `HEAD` in other VCSs you may be used to, such as Subversion or CVS. -In Git, this is a pointer to the local branch you're currently on. -In this case, you're still on `master`. -The `git branch` command only _created_ a new branch -- it didn't switch to that branch. +چگونه گیت می‌داند که روی چه برنچی کار می‌کنید؟ +گیت نشانگر خاصی به نام `HEAD` (هد) را در خود دارد. +به خاطر داشته باشید این مفهوم تفاوت زیادی با مفهوم `HEAD` در دیگر VCSها، مانند ساب‌ورژن یا CVS، دارد که ممکن است از پیشتر به یاد داشته باشید. +در گیت، هد نشانگری است که به برنچ محلی که روی آن هستید اشاره می‌کند. +در مثالی که روی آن کار می‌کنیم شما هنوز روی `master` هستید. +دستور `git branch` فقط یک برنچ جدید _ساخت_ -- به برنچ جدید نقل مکان نکرد. -.HEAD pointing to a branch +.هد که به یک برنچ اشاره می‌کند image::images/head-to-master.png[HEAD pointing to a branch.] -You can easily see this by running a simple `git log` command that shows you where the branch pointers are pointing. -This option is called `--decorate`. +به سادگی هر چه تمام شما می‌توانید با اجرای دستور `git log`، که به شما نشان می‌دهد چه برنچی به کجا اشاره دارد، این موضوع را بررسی کنید. +این آپشن `--decorate` خوانده می‌شود. [source,console] ---- $ git log --oneline --decorate -f30ab (HEAD -> master, testing) add feature #32 - ability to add new formats to the central interface -34ac2 Fixed bug #1328 - stack overflow under certain conditions -98ca9 The initial commit of my project +f30ab (HEAD -> master, testing) Add feature #32 - ability to add new formats to the central interface +34ac2 Fix bug #1328 - stack overflow under certain conditions +98ca9 Initial commit ---- -You can see the ``master'' and ``testing'' branches that are right there next to the `f30ab` commit. +شما می‌توانید برنچ‌های `master` و `testing` را که دقیقاً کنار کامیت `f30ab` هستند ببینید. [[_switching_branches]] -==== Switching Branches +==== تعویض شاخه‌ها (((branches, switching))) -To switch to an existing branch, you run the `git checkout` command.(((git commands, checkout))) -Let's switch to the new `testing` branch: +برای تعویض یا جابه‌جایی به یک برنچ از پیش ساخته شده دستور `git checkout` را اجرا می‌کنید.(((git commands, checkout))) +حال بیایید به برنچ جدید `testing` برویم: [source,console] ---- $ git checkout testing ---- -This moves `HEAD` to point to the `testing` branch. +این کار `HEAD` را جابه‌جا می‌کند تا به برنچ `testing` اشاره کند. -.HEAD points to the current branch +.هد به برنچ فعلی اشاره می‌کند image::images/head-to-testing.png[HEAD points to the current branch.] -What is the significance of that? -Well, let's do another commit: +تأثیر این کار در چه بود؟ +خب، بیایید یک کامیت دیگر انجام دهیم: [source,console] ---- @@ -113,34 +117,46 @@ $ vim test.rb $ git commit -a -m 'made a change' ---- -.The HEAD branch moves forward when a commit is made +.هنگامی که کامیتی ساخته می‌شود برنچ هد به جلو می‌رود image::images/advance-testing.png[The HEAD branch moves forward when a commit is made.] -This is interesting, because now your `testing` branch has moved forward, but your `master` branch still points to the commit you were on when you ran `git checkout` to switch branches. -Let's switch back to the `master` branch: +این مسئله جالب است چرا که الآن برنچ `testing` به جلو رفت در حالی که برنچ `master` هنوز به کامیتی که سابقاً، حین اجرای `git checkout` که برای تعویض برنچ‌ها استفاده شد، اشاره می‌کند. +بیایید دوباره به برنچ `master` بازگردیم: [source,console] ---- $ git checkout master ---- -.HEAD moves when you checkout +[NOTE] +.`git log` _همیشه_، _همهٔ_ برنچ‌ها را نمایش نمی‌دهد. +==== +اگر الآن `git log` را اجرا می‌کردید ممکن بود از اینکه برنچ «testing»ـی که همین الآن ساختید کجا رفت متعجب شوید، چرا که قاعدتاً نباید در خروجی نمایش داده شود. + +برنچ مذکور غیب نشده است؛ صرفاً گیت گمان نمی‌کند که شما علاقه‌ای به دانستن اطلاعات آن برنچ دارید و سعی می‌کند مطالبی که به نظرش برای شما مفید است را به شما نشان دهد. +به بیان دیگر، در حالت پیش‌فرض، `git log` فقط تاریخچهٔ کامیت‌های زیر برنچی که شما چک‌اوت کرده‌اید را نمایش می‌دهد. + +برای نمایش تاریخچهٔ کامیت‌های برنچ مورد نظر باید به صراحت آن را نام ببرید: `git log testing`. +برای نمایش تمام برنچ‌ها `--all` را به دستور `git log`تان بی‌افزایید. +==== + +.وقتی چک‌اوت می‌کنید هد جابه‌جا می‌شود image::images/checkout-master.png[HEAD moves when you checkout.] -That command did two things. -It moved the HEAD pointer back to point to the `master` branch, and it reverted the files in your working directory back to the snapshot that `master` points to. -This also means the changes you make from this point forward will diverge from an older version of the project. -It essentially rewinds the work you've done in your `testing` branch so you can go in a different direction. +آن دستور دو کار اصلی انجام داد. +نشانگر هد را بازگردان تا به برنچ `master` اشاره کند و فایل‌هایی که در پوشه کاری کاری شما بودند را به اسنپ‌شاتی که `master` به آن اشاره می‌کرد بازگردانی (Revert/ریورت) کرد. +این مسئله همچنین به این معنا است که تغییراتی که از این نقطه به بعد اعمال کنید از نسخه‌های قدیمی‌تر پروژه جدا خواهد ماند. +در ساده‌ترین تعریف، کاری که در برنچ `testing` کردید را خنثی می‌کند تا بتوانید راه دیگری را در پیش بگیرید. [NOTE] -.Switching branches changes files in your working directory +.تعویض برنچ فایل‌های درون پوشه کاری را تغییر می‌دهد ==== -It's important to note that when you switch branches in Git, files in your working directory will change. -If you switch to an older branch, your working directory will be reverted to look like it did the last time you committed on that branch. -If Git cannot do it cleanly, it will not let you switch at all. +بسیار مهم است که به خاطر داشته باشید که تعویض برنچ در گیت فایل‌هایی که در پوشه کاری دارید را تغییر می‌دهد. +اگر به برنچ قدیمی‌تری انتقال پیدا کنید، پوشه کاری شما به آن صورتی بازگردانی خواهد شد که آخرین بار هنگام ایجاد کامیت بود روی آن برنچ بوده است. +اگر گیت نتواند این بازگردانی را به صورت بی‌نقص انجام دهد، نمی‌گذارد که تعویض برنچ انجام شود. ==== -Let's make a few changes and commit again: +بیایید چند تغییر جدید اعمال کنیم و دوباره کامیت بگیریم: [source,console] ---- @@ -148,35 +164,41 @@ $ vim test.rb $ git commit -a -m 'made other changes' ---- -Now your project history has diverged (see <>). -You created and switched to a branch, did some work on it, and then switched back to your main branch and did other work. -Both of those changes are isolated in separate branches: you can switch back and forth between the branches and merge them together when you're ready. -And you did all that with simple `branch`, `checkout`, and `commit` commands. +اکنون تاریخچه پروژه شما دوشاخه شده است (به <> مراجعه کنید). +شما یک برنچ ساختید و به آن انتقال پیدا کردید، کمی روی آن کار کردید و سپس به برنچ اصلیتان بازگشتید و کمی کار متفاوت آنجا انجام دادید. +هر دوی آن تغییرات به صورت ایزوله در برنچ‌های خودشان موجوداند: شما می‌توانید بین برنچ‌ها جابه‌جا شوید و هرگاه آماده بودید آنها را با هم مرج کنید. +و جالبتر اینکه همهٔ این کارها صرفاً با دستورهای `branch`، `checkout` و `commit` انجام دادید. [[divergent_history]] -.Divergent history +.تاریخچه دوشاخه شده image::images/advance-master.png[Divergent history.] -You can also see this easily with the `git log` command. -If you run `git log --oneline --decorate --graph --all` it will print out the history of your commits, showing where your branch pointers are and how your history has diverged. +علاوه بر آن، با دستور `git log` می‌توانید این اطلاعات را ببینید. +اگر `git log --oneline --decorate --graph --all` را اجرا کنید، برنامه تاریخچهٔ کامیت‌های شما را نمایش می‌دهد، نشان می‌دهد که نشانگرهای برنچ‌هایتان کجاست و چگوننه تاریخچهٔ شما دو شاخه شده است. [source,console] ---- $ git log --oneline --decorate --graph --all -* c2b9e (HEAD, master) made other changes -| * 87ab2 (testing) made a change +* c2b9e (HEAD, master) Made other changes +| * 87ab2 (testing) Made a change |/ -* f30ab add feature #32 - ability to add new formats to the -* 34ac2 fixed bug #1328 - stack overflow under certain conditions +* f30ab Add feature #32 - ability to add new formats to the central interface +* 34ac2 Fix bug #1328 - stack overflow under certain conditions * 98ca9 initial commit of my project ---- -Because a branch in Git is actually a simple file that contains the 40 character SHA-1 checksum of the commit it points to, branches are cheap to create and destroy. -Creating a new branch is as quick and simple as writing 41 bytes to a file (40 characters and a newline). +از این جهت که برنچ در گیت صرفاً یک فایل سادهٔ محتوی یک چک‌سام SHA-1 چهل حرفی کامیتی است که به آن اشاره می‌کند، ساختن و از بین بردن برنچ‌ها کم هزینه است. +ساختن یک برنچ جدید به سادگی و سرعت نوشتن ۴۱ بایت اطلاعات درون یک فایل است (۴۰ حرف و یک خط جدید). + +این قضیه بسیار متفاوت با نحوهٔ برنچ‌سازی ابزارهای VCS قدیمی است که شامل کپی کردن تمام فایل‌های پروژه به یک پوشه ثانوی می‌باشد. +این می‌تواند چندین ثانیه یا حتی دقیقه، بسته به سایز پروژه، طول بکشد؛ درحالی که در گیت این فرآیند همیشه آنی است. +همچنین به علت اینکه هنگامی که کامیت می‌کنیم والد را هم در کامیت ثبت می‌کنیم، پیدا کردن یک پایهٔ ادغام برای مرج کردن به صورت خودکار برای ما انجام می‌شود و به طور کل به سهولت انجام می‌پذیرد. +معمولاً مزایا توسعه‌دهندگان را به ساختن و استفاده از برنچ‌ها مشتاق می‌کند. -This is in sharp contrast to the way most older VCS tools branch, which involves copying all of the project's files into a second directory. -This can take several seconds or even minutes, depending on the size of the project, whereas in Git the process is always instantaneous. -Also, because we're recording the parents when we commit, finding a proper merge base for merging is automatically done for us and is generally very easy to do. -These features help encourage developers to create and use branches often. +بیایید به اینکه چرا باید شما هم از این کار را کنید نگاهی بیاندازیم. -Let's see why you should do so. +[NOTE] +.ساختن یک برنچ جدید و انتقال به آن در آن واحد +==== +خیلی اوقات پیش می‌آید که یک برنچ جدید بسازید و در آن واحد بخواهید به آن انتقال یابید -- این کار در یک عملیات با `git checkout -b ` قابل انجام است. +==== diff --git a/book/03-git-branching/sections/rebasing.asc b/book/03-git-branching/sections/rebasing.asc index f64d0ae85..8ab088ea2 100644 --- a/book/03-git-branching/sections/rebasing.asc +++ b/book/03-git-branching/sections/rebasing.asc @@ -1,28 +1,29 @@ [[_rebasing]] -=== Rebasing +=== ریبیس‌کردن (((rebasing))) -In Git, there are two main ways to integrate changes from one branch into another: the `merge` and the `rebase`. -In this section you'll learn what rebasing is, how to do it, why it's a pretty amazing tool, and in what cases you won't want to use it. +در گیت دو راه اصلی برای تعبیه تغییرات از برنچی به برنچ دیگر وجود دارد: `merge` و `rebase`. +در این بخش شما خواهید آموخت که ریبیس (Rebase) چیست، چکار می‌کند، چرا ابزار شگفت‌انگیزی است و در چه شرایطی نمی‌خواهید از آن استفاده کنید. -==== The Basic Rebase +==== ریبیس مقدماتی -If you go back to an earlier example from <<_basic_merging>>, you can see that you diverged your work and made commits on two different branches. +اگر به یک مثال قدیمی‌تر از <<_basic_merging>> بازگردیم، می‌بینید که کار شما و کامیت‌های که کرده‌اید دوشاخه شده است. -.Simple divergent history +.تاریخچهٔ دوشاخهٔ ساده image::images/basic-rebase-1.png[Simple divergent history.] -The easiest way to integrate the branches, as we've already covered, is the `merge` command. -It performs a three-way merge between the two latest branch snapshots (`C3` and `C4`) and the most recent common ancestor of the two (`C2`), creating a new snapshot (and commit). +همانطور که قبلاً بررسی کردیم، آسان‌ترین راه برای یکپارچه‌سازی برنچ‌ها دستور `merge` است +این دستور یک ادغام‌سازی سه طرفه بین آخرین اسنپ‌شات‌های دو برنچ ‌(`C3` و `C4`) و آخرین والد مشترک آنها (`C2`) انجام می‌دهد، یک اسنپ‌شات جدید می‌سازد (و آنرا کامیت می‌کند). -.Merging to integrate diverged work history +[[rebasing-merging-example]] +.مرج کردن تاریخچه‌های دوشاخه شده image::images/basic-rebase-2.png[Merging to integrate diverged work history.] -However, there is another way: you can take the patch of the change that was introduced in `C4` and reapply it on top of `C3`. -In Git, this is called _rebasing_. -With the `rebase` command, you can take all the changes that were committed on one branch and replay them on another one.(((git commands, rebase))) +هرچند راه دیگری نیز وجود دارد: شما می‌توانید پچ تغییراتی که در `C4` معرفی شده‌اند را گرفته و آنرا به بالای `C3` اعمال کنید. +در گیت این عمل _ریبیس‌کردن_ نامیده می‌شود. +با دستور `rebase` شما می‌توانید تمام تغییراتی که روی یک برنچ کامیت شده‌اند را بگیرید و آنها را به برنچ دیگر اعمال کنید.(((git commands, rebase))) -In this example, you'd run the following: +برای این مثال شما برنچ `experiment` را چک‌اوت می‌کنید و بعد آنرا به `master` ریبیس می‌کنید، که به این شکل است: [source,console] ---- @@ -32,12 +33,13 @@ First, rewinding head to replay your work on top of it... Applying: added staged command ---- -It works by going to the common ancestor of the two branches (the one you're on and the one you're rebasing onto), getting the diff introduced by each commit of the branch you're on, saving those diffs to temporary files, resetting the current branch to the same commit as the branch you are rebasing onto, and finally applying each change in turn. +این عملیات به این صورت کار می‌کند که به والد مشترک دو برنچ می‌رود (آنکه رویش قرار دارید و آنکه به رویش ریبیس‌ می‌کنید)، تفاوت (Diff) معرفی شده توسط هر کامیت برنچی که روی آن هستید +را می‌گیرد، آن دیف‌ها را روی فایل‌های موقت می‌ریزد، برنچ فعلی را به جایی که برنچی که روی آن ریبیس می‌کنید بازنشانی می‌کند و در نهایت تغییرات را به ترتیب اعمال می‌کند. -.Rebasing the change introduced in `C4` onto `C3` +.ریبیس کردن تغییرات معرفی شده در `C4` به روی `C3` image::images/basic-rebase-3.png[Rebasing the change introduced in `C4` onto `C3`.] -At this point, you can go back to the `master` branch and do a fast-forward merge. +در این نقطه می‌توانید به برنچ `master` بازگردید و تغییرات را به صورت fast-forward مرج کنید. [source,console] ---- @@ -45,47 +47,47 @@ $ git checkout master $ git merge experiment ---- -.Fast-forwarding the master branch -image::images/basic-rebase-4.png[Fast-forwarding the master branch.] +.fast-forward کردن برنچ `master` +image::images/basic-rebase-4.png[Fast-forwarding the `master` branch.] -Now, the snapshot pointed to by `C4'` is exactly the same as the one that was pointed to by `C5` in the merge example. -There is no difference in the end product of the integration, but rebasing makes for a cleaner history. -If you examine the log of a rebased branch, it looks like a linear history: it appears that all the work happened in series, even when it originally happened in parallel. +حال اسنپ‌شاتی که `C4'` به آن اشاره می‌کند دقیقاً به مانند همانی است که که سابقاً توسط `C5` در <> به آن اشاره می‌شد. +تفاوتی در محصول نهایی این یکپارچه‌سازی وجود ندارد اما ریبیس‌کردن تاریخچه‌ای تمیزتر را خلق می‌کند. +اگر لاگ یک برنچ ریبیس‌شده را مطالعه کنید، به نظر یک تاریخچهٔ خط است: طوری نمایش داده می‌شود که انگار همه چیز در طی یک فرآیند سری اتفاق افتاده حتی اگر در حقیقت به طور +موازی انجام شده است. -Often, you'll do this to make sure your commits apply cleanly on a remote branch -- perhaps in a project to which you're trying to contribute but that you don't maintain. -In this case, you'd do your work in a branch and then rebase your work onto `origin/master` when you were ready to submit your patches to the main project. -That way, the maintainer doesn't have to do any integration work -- just a fast-forward or a clean apply. +توجه داشته باشید که اسنپ‌شاتی که توسط کامیت نهایی تولیدی به آن اشاره می‌شود (چه آخرین کامیت ریبیس‌شده باشد، چه آخرین کامیت پس از مرج باشید) همان اسنپ‌شات است -- +فقط تاریخچه تغییر کرده است. +ریبیس‌کردن از خطی که در آن تغییرات معرفی شده‌اند به خط دیگر باز اعمال می‌کند، درحالی که مرج نقاط نهایی را می‌گیرد و آنها را ادغام می‌کند. -Note that the snapshot pointed to by the final commit you end up with, whether it's the last of the rebased commits for a rebase or the final merge commit after a merge, is the same snapshot – it's only the history that is different. -Rebasing replays changes from one line of work onto another in the order they were introduced, whereas merging takes the endpoints and merges them together. +==== ریبیس‌های جذاب‌تر -==== More Interesting Rebases - -You can also have your rebase replay on something other than the rebase target branch. -Take a history like <>, for example. -You branched a topic branch (`server`) to add some server-side functionality to your project, and made a commit. -Then, you branched off that to make the client-side changes (`client`) and committed a few times. -Finally, you went back to your server branch and did a few more commits. +شما همچنین می‌توانید تغییرات را روی چیزی به غیر از برنچ هدف اعمال کنید. +به طور مثال یک تاریخچه مانند <> را در نظر بگیرید. +یک برنچ موضوعی (`server`) ساختید تا چند مورد سمت سرور به پروژهٔ خود اضافه کنید و کامیتی گرفتید. +سپس یک برنچ ساختید (`client`) تا تغییرات سمت کلاینت را اعمال کنید و چند کامیت هم آنجا گرفتید. +در نهایت به برنچ سرور بازگشتید و چند کامیت دیگر گرفته‌اید. [[rbdiag_e]] -.A history with a topic branch off another topic branch +.یک تاریخچه با یک برنچ موضوعی که از برنچ موضوعی دیگر شروع می‌شود image::images/interesting-rebase-1.png[A history with a topic branch off another topic branch.] -Suppose you decide that you want to merge your client-side changes into your mainline for a release, but you want to hold off on the server-side changes until it's tested further. -You can take the changes on client that aren't on server (`C8` and `C9`) and replay them on your `master` branch by using the `--onto` option of `git rebase`: +با فرض اینکه تصمیم دارید که تغیرات سمت کلاینت را در خط اصلی پروژه ادغام کنید ولی می‌خواهید که تغییرات سمت سرور تا زمان تست شدن باقی بمانند. +شما می‌توانید با استفاده از آپشن `--onto` از دستور `git rebase` تغییراتی از `client` را که در `server` نیستند (`C8` و `C9`) را گرفته و آنها را روی برنچ `master` اعمال کنید: [source,console] ---- $ git rebase --onto master server client ---- -This basically says, ``Take the `client` branch, figure out the patches since it diverged from the `server` branch, and replay these patches in the `client` branch as if it was based directly off the `master` branch instead.'' -It's a bit complex, but the result is pretty cool. +این دستور خیلی ساده می‌گوید که «برنچ `client` را بگیر، از زمانی که از `server` جدا شده تغییراتش را بررسی کن و آنها را به برنچ `client` دوباره طوری اعمال که انگار برنچ مستقیماً +از پایهٔ `master` شروع شده بوده.» +کمی پیچیده است اما نتایجش جالب هستند. + -.Rebasing a topic branch off another topic branch +.ریبیس کردن یک برنچ موضوعی از یک برنچ موضوعی دیگر image::images/interesting-rebase-2.png[Rebasing a topic branch off another topic branch.] -Now you can fast-forward your `master` branch (see <>): +حال می‌توانید برنچ `master` خود را fast-forward کنید (به <> نگاهی بیاندازید): [source,console] ---- @@ -94,24 +96,25 @@ $ git merge client ---- [[rbdiag_g]] -.Fast-forwarding your master branch to include the client branch changes -image::images/interesting-rebase-3.png[Fast-forwarding your master branch to include the client branch changes.] +.fast-forward کردن برنچ `master` برای اضافه کردن تغییرات برنچ کلاینت +image::images/interesting-rebase-3.png[Fast-forwarding your `master` branch to include the client branch changes.] -Let's say you decide to pull in your server branch as well. -You can rebase the server branch onto the `master` branch without having to check it out first by running `git rebase ` -- which checks out the topic branch (in this case, `server`) for you and replays it onto the base branch (`master`): +بیایید فرض کنیم که تصمیم گرفته‌اید که برنچ سرور خود را نیز پول کنید. +با `git rebase ` اجرای شما می‌توانید برنچ `server` را روی `master` ریبیس کنید بدون آنکه مجبور باشید ابتدا آنرا چک‌اوت کنید -- این دستور برای شما +برنچ موضوعی را چک‌اوت می‌کند (در این مثال `server`) و تغییرات آنرا روی برنچ پایه (بیس) (`master`) بازاعمال می‌کند. [source,console] ---- $ git rebase master server ---- -This replays your `server` work on top of your `master` work, as shown in <>. +همانطور که در <> نمایش داده شد، این دستور کارهای برنچ `server` را روی کارهای `master` شما سوار می‌کند. [[rbdiag_h]] -.Rebasing your server branch on top of your master branch -image::images/interesting-rebase-4.png[Rebasing your server branch on top of your master branch.] +.ریبیس کردن برنچ سرورتان روی برنچ `master` +image::images/interesting-rebase-4.png[Rebasing your server branch on top of your `master` branch.] -Then, you can fast-forward the base branch (`master`): +پس از این می‌توانید برنچ پایه (`master`) را fast-forward کنید: [source,console] ---- @@ -119,7 +122,7 @@ $ git checkout master $ git merge server ---- -You can remove the `client` and `server` branches because all the work is integrated and you don't need them anymore, leaving your history for this entire process looking like <>: +شما متوانید برنچ‌های `client` و `server` را حذف کنید چار که تمام کارها تعبیه شده‌اند و شما دیگر به آنها احتیاجی ندارید. با این کار تمام تاریخچه شما مشابه <> خواهد بود: [source,console] ---- @@ -128,109 +131,114 @@ $ git branch -d server ---- [[rbdiag_i]] -.Final commit history +.تاریخچهٔ کامیت نهایی image::images/interesting-rebase-5.png[Final commit history.] [[_rebase_peril]] -==== The Perils of Rebasing +==== خطرات ریبیس‌کردن (((rebasing, perils of))) -Ahh, but the bliss of rebasing isn't without its drawbacks, which can be summed up in a single line: +ولی، ریبیس هم مشکلات خودش را دارد، مشکلاتی که در یک خط خلاصه می‌توان از آنها اجتناب کرد: -*Do not rebase commits that exist outside your repository.* +*کامیت‌هایی که خارج از مخزن شما هستند و یا کار دیگران به آن بستگی دارد را ریبیس نکنید.* -If you follow that guideline, you'll be fine. -If you don't, people will hate you, and you'll be scorned by friends and family. +اگر این راهنما را به گوش بسپارید،‌با مشکلی مواجه نخواهید شد. +اما اگر نکنید، ملت از شما متنفر خواهید شد و شما توسط دوستان و خانوادهٔ خود ترد خواهید شد. -When you rebase stuff, you're abandoning existing commits and creating new ones that are similar but different. -If you push commits somewhere and others pull them down and base work on them, and then you rewrite those commits with `git rebase` and push them up again, your collaborators will have to re-merge their work and things will get messy when you try to pull their work back into yours. +وقتی چیزی را ریبیس می‌کنید، در حال پشت سر گذاشتن کامیت‌های حاضر و ساختن کامیت‌های شبیه آنها، اما متفاوت، هستید. +اگر جایی این کامیت‌ها را پوش کنید و دیگران آنها را پول کرده و روی آنها کار کنند و سپس شما آن کامیت‌ها را با `git rebase` بازنویسی و دوباره پوش کنید، همکاران شما مجبور +خواهند بود تا دوباره کار خود را باز-ادغام کنند و هنگامی که بخواهید کار آنها را به کار خودتان پول کنید همه‌چیز، حتی بیش از پیش، فاجعه‌بارتر خواهد شد. -Let's look at an example of how rebasing work that you've made public can cause problems. -Suppose you clone from a central server and then do some work off that. -Your commit history looks like this: +بیایید نگاهی به اینکه چگونه یک ریبیس که به صورت عمومی انجام داده‌اید می‌تواند مشکل‌ساز باشد بیاندازیم. +فرض کنیم که شما از یک سرور مرکزی کلون کرده‌اید و سپس کمی کار روی آن انجام داده‌اید. +تاریخچهٔ کامیت شما شبیه زیر است: -.Clone a repository, and base some work on it +.یک مخزن را کلون می‌کنید و کمی کار روی آن انجام می‌دهید‌ image::images/perils-of-rebasing-1.png["Clone a repository, and base some work on it."] -Now, someone else does more work that includes a merge, and pushes that work to the central server. -You fetch it and merge the new remote branch into your work, making your history look something like this: +حال شخص دیگری نیز کمی کار محتوی یک مرج انجام می‌دهد و آنرا به سرور مرکزی پوش می‌کند. +شما آنرا فچ می‌کنید و برنچ ریموت جدید را در کار خود مرج می‌کنید که باعث می‌شود تاریخچهٔ شما به شکل زیر شود: +.کامیت‌های بیشتری را فچ می‌کنید و آنها را با کار خود مرج می‌کنید .Fetch more commits, and merge them into your work image::images/perils-of-rebasing-2.png["Fetch more commits, and merge them into your work."] -Next, the person who pushed the merged work decides to go back and rebase their work instead; they do a `git push --force` to overwrite the history on the server. -You then fetch from that server, bringing down the new commits. +پس از این، شخصی که کار مرج‌شده را پوش کرده تصمیم می‌گیرد که باز گردد و بجای آن کار خود را ریبیس کند؛ او یک `git push --force` می‌کند تا تاریخچهٔ سرور را بازنویسی کند. +سپس شما آن سرور را فچ می‌کنید و کامیت‌های جدید را دریافت می‌کنید: [[_pre_merge_rebase_work]] -.Someone pushes rebased commits, abandoning commits you've based your work on +.شخصی کامیت‌های ریبیس‌شده را پوش می‌کند، کامیت‌هایی که شما کار خود را روی آنها بنا گذاشته‌اید را پشت سر می‌گذارد image::images/perils-of-rebasing-3.png["Someone pushes rebased commits, abandoning commits you've based your work on."] -Now you're both in a pickle. -If you do a `git pull`, you'll create a merge commit which includes both lines of history, and your repository will look like this: +حالا هر دوی شما گیر افتاده‌اید. +اگر شما `git pull` کنید، یک مرج کامیت خواهید ساخت که شامل هر دو خط از تاریخچه خواهد بود و مخزن شما به شکل زیر در خواهد آمد: [[_merge_rebase_work]] -.You merge in the same work again into a new merge commit +.شما همان کارها را دوباره مرج می‌کنید و یک مرج کامیت جدید می‌سازید image::images/perils-of-rebasing-4.png[You merge in the same work again into a new merge commit.] -If you run a `git log` when your history looks like this, you'll see two commits that have the same author, date, and message, which will be confusing. -Furthermore, if you push this history back up to the server, you'll reintroduce all those rebased commits to the central server, which can further confuse people. -It's pretty safe to assume that the other developer doesn't want `C4` and `C6` to be in the history; that's why they rebased in the first place. +اگر در همین حین که تاریخچهٔ شما به این شکل است، یک `git log` اجرا کنید خواهید دید که دو کامیت وجود دارد که دقیقاً یک نویسنده، تاریخ و پیغام دارند که می‌تواند بسیار گیج‌کننده باشد. +بعلاوه اگر این تاریخچه را به سرور پوش کنید، شما تمام آن کامیت‌های ریبیس شده را دوباره به سرور مرکزی معرفی می‌کنید که به مقدار گیج‌کنندگی مسئله بیش از پیش می‌افزاید. +خیلی راحت می‌توان فرض را بر این گذاشت که توسعه‌دهندگان دیگر نمی‌خواهند که `C4` و `C6` در تاریخچه باشند و همین باعث بوده که در وهله اول ریبیس انجام شود. [[_rebase_rebase]] -==== Rebase When You Rebase +==== وقتی ریبیس می‌کنید ریبیس کنید -If you *do* find yourself in a situation like this, Git has some further magic that might help you out. -If someone on your team force pushes changes that overwrite work that you've based work on, your challenge is to figure out what is yours and what they've rewritten. +اگر شما خودتان را در چنین شرایطی می‌بینید، گیت کمی راه حل جادویی پیش پای شما گذاشته است که ممکن است به شما کمک کنند. +اگر شخصی در تیمتان فورس پوشی کرده که کاری که پایهٔ کار شما را بازنویسی کرده است، چالش شما تشخیص این خواهد بود که چه کاری مال شماست و چه چیزی را آنها بازنویسی کرده‌اند. -It turns out that in addition to the commit SHA-1 checksum, Git also calculates a checksum that is based just on the patch introduced with the commit. -This is called a ``patch-id''. +در اینجا معلوم می‌شود که علاوه بر چک‌سام SHA-1 کامیت، گیت همچنین چک‌سامی از تغییراتی که کامیت به تاریخچه افزوده محاسبه می‌کند. +این چک‌سام را «شناسهٔ پچ» (Patch-ID) می‌خوانیم. -If you pull down work that was rewritten and rebase it on top of the new commits from your partner, Git can often successfully figure out what is uniquely yours and apply them back on top of the new branch. +اگر کاری که بازنویسی شده را پول کرده‌اید و آنرا به روی کامیت‌های جدید همکارتان ریبیس کنید، اکثر مواقع گیت متوجه می‌شود که چه کاری منحصر به شماست و آنها را دوباره به +بالای برنچ جدید اعمال می‌کند. -For instance, in the previous scenario, if instead of doing a merge when we're at <<_pre_merge_rebase_work>> we run `git rebase teamone/master`, Git will: +به طور مثال، در شرایط قبلی، اگر هنگامی که در <<_pre_merge_rebase_work>> هستید به جای مرج‌کردن، `git rebase teamone/master` را اجرا کنید، گیت: -* Determine what work is unique to our branch (C2, C3, C4, C6, C7) -* Determine which are not merge commits (C2, C3, C4) -* Determine which have not been rewritten into the target branch (just C2 and C3, since C4 is the same patch as C4') -* Apply those commits to the top of `teamone/master` +* خواهد فهمید که چه کاری مختص به برنچ ماست (C2، C3، C4، C6، C7) +* خواهد فهمید کدام کامیت‌ها مرج نشده‌اند (C2، C3، C4) +* خواهد فهمید کدام کایمت‌ها به برنچ مورد نظر بازنویسی نشده‌اند (فقط C2 و C3، از آنجایی که C4 همان پچ C4' است) +* آن کامیت‌ها را به روی `teamone/master` اعمال خواهد کرد -So instead of the result we see in <<_merge_rebase_work>>, we would end up with something more like <<_rebase_rebase_work>>. +بنابراین بجای برخوردن با <<_merge_rebase_work>> با نتیجه‌ای بیشتر شبیه <<_rebase_rebase_work>> مواجه خواهیم شد. [[_rebase_rebase_work]] -.Rebase on top of force-pushed rebase work. +.به روی یک کار ریبیس و فورس پوش شده ریبیس می‌کنید image::images/perils-of-rebasing-5.png[Rebase on top of force-pushed rebase work.] -This only works if C4 and C4' that your partner made are almost exactly the same patch. -Otherwise the rebase won't be able to tell that it's a duplicate and will add another C4-like patch (which will probably fail to apply cleanly, since the changes would already be at least somewhat there). +این فقط در شرایط کار خواهد کرد که `C4` و `C4'` که همکار شما ساخته تقریباً تغییرات یکسانی داشته باشند. +در غیر این صورت ریبیس به شما نخواهد گفت که تغییرات کپی هستند و یک پچ شبه-C4 (که احتمالاً اعمالش شکست خواهد خورد چراکهتغییرات قبلاً یک جایی پیاده‌سازی شده‌اند) می‌سازد. -You can also simplify this by running a `git pull --rebase` instead of a normal `git pull`. -Or you could do it manually with a `git fetch` followed by a `git rebase teamone/master` in this case. +شما می‌توانید به سادگی و با اجرای `git pull --rebase` به جای یک `git pull` معمولی این کار را انجام دهید. +یا می‌توانستید با یک `git fetch` که پس از آن `git rebase teamone/master` (با توجه به مثال) اجرا شده به طور دستی اعمال کنید. -If you are using `git pull` and want to make `--rebase` the default, you can set the `pull.rebase` config value with something like `git config --global pull.rebase true`. +اگر از `git pull` استفاده می‌کنید و می‌خواهید `--rebase` پیش‌فرض باشد، می‌توانید مقدار کانفیگ `pull.rebase` را با دستوری مانند `git config --global pull.rebase true` تنظیم کنید. -If you treat rebasing as a way to clean up and work with commits before you push them, and if you only rebase commits that have never been available publicly, then you'll be fine. -If you rebase commits that have already been pushed publicly, and people may have based work on those commits, then you may be in for some frustrating trouble, and the scorn of your teammates. +اگر شما فقط کامیت‌هایی که هرگز کامپیوتر شما را ترک نکرده‌اند ریبیس می‌کنید به مشکلی بر نخواهید خورد. +اگر کامیت‌هایی را ریبیس می‌کنید که پوش شده‌اند اما هیچ شخص دیگری روی آنها کاری را شروع نکرده است باز هم به مشکلی بر نخواهید خورد. +اگر کامیت‌هایی را ریبیس می‌کنید که به طور عمومی پوش کرده‌اید و ممکن است اشخاصی روی آنها کار کرده باشند، ممکن است در دردسر طاقت‌فرسایی افتاده باشید و توسط هم تیمی‌هایتان ترد شوید. -If you or a partner does find it necessary at some point, make sure everyone knows to run `git pull --rebase` to try to make the pain after it happens a little bit simpler. +اگر شما یا همکارتان به این نتیجه رسید که انجام چنین کاری ضروری است، از اینکه همه `git pull --rebase` را اجرا می‌کنند تا در آینده درد کمتری نسیبتان شود مطمئن شوید. -==== Rebase vs. Merge +==== ریبیس در مقابل مرج (((rebasing, vs. merging)))(((merging, vs. rebasing))) -Now that you've seen rebasing and merging in action, you may be wondering which one is better. -Before we can answer this, let's step back a bit and talk about what history means. +حال که ریبیس و مرج را در عمل دیدید،‌ممکن است به این فکر کنید که کدام بهتر است. +پیش از اینکه به آن پاسخ دهیم بیایید کمی به عقب بازگردیم و به مبحث اینکه تاریخچه چه معنایی دارد بپردازیم. -One point of view on this is that your repository's commit history is a *record of what actually happened.* -It's a historical document, valuable in its own right, and shouldn't be tampered with. -From this angle, changing the commit history is almost blasphemous; you're _lying_ about what actually transpired. -So what if there was a messy series of merge commits? -That's how it happened, and the repository should preserve that for posterity. +از دیدگاهی تاریخچهٔ کامیت‌‌های مخزن شما *ثبت وقایع اتفاق افتاده است.* +سندی تاریخی و با ارزش است که نباید با آن خیلی بازی کرد. +از این زاویه دید تغییر دادن تاریخچهٔ کامیت‌ها تقریباً تعریف را نقض می‌کند؛ شما در حال _دروغ گفتن_ دربارهٔ اتفاقاتی که واقعاً افتاده هستید. +پس اگر دسته‌ای از مرج کامیت‌های شلوغ داشته باشیم چه کنیم؟ +اتفاقی است که افتاده و مخزن باید آنرا برای آیندگان نگه دارد. -The opposing point of view is that the commit history is the *story of how your project was made.* -You wouldn't publish the first draft of a book, and the manual for how to maintain your software deserves careful editing. -This is the camp that uses tools like rebase and filter-branch to tell the story in the way that's best for future readers. +در نقطه مقابل دیدگاهی است که که می‌گوید تاریخچهٔ کامیت‌ها *داستان چگونگی ساخت پروژهٔ شما است.* +پیش نمی‌آید که اولین پیش‌نویس یک کتاب را یا راهنمایی برای اینکه «چرا نرم‌افزارتان مستحق ویرایش‌های محتاطانه است» منتشر کنید. +افرادی که این دیدگاه را دارند از ابزارهایی مانند `rebase` و `filter-branch` استفاده می‌کنند تا داستان را به نحوی بسرایند که برای خوانندگان احتمالی پخته باشد. -Now, to the question of whether merging or rebasing is better: hopefully you'll see that it's not that simple. -Git is a powerful tool, and allows you to do many things to and with your history, but every team and every project is different. -Now that you know how both of these things work, it's up to you to decide which one is best for your particular situation. +حال برای جواب دادن به اینکه مرج بهتر است یا ریبیس: خوشبختانه ملاحظه می‌کنید که جواب دادن خیلی ساده نیست. +گیت ابزار قدرتمندی است، به شما اجازهٔ انجام خیلی کار‌ها را به خصوص روی تاریخچه‌تان می‌دهد، اما هر تیم و هر پروژه متفاوت است. +حال که می‌دانید چگونه اینها کار می‌کنند، به شما بستگی دارد که تصمیم بگیرید که کدام برای شرایط بخصوص شما بهترین است. -In general the way to get the best of both worlds is to rebase local changes you've made but haven't shared yet before you push them in order to clean up your story, but never rebase anything you've pushed somewhere. +در کل بهترین حالت ممکن این است که تغییرات محلی را که اعمال کرده‌اید اما منتشر نکرده‌اید ریبیس کنید تا پیش از پوش تاریخچهٔ شما تمیز باشد، اما هرگز هیچ چیزی را که جایی پوش +کرده‌اید ریبیس نکنید. diff --git a/book/03-git-branching/sections/remote-branches.asc b/book/03-git-branching/sections/remote-branches.asc index a8f448193..3e20f756e 100644 --- a/book/03-git-branching/sections/remote-branches.asc +++ b/book/03-git-branching/sections/remote-branches.asc @@ -1,71 +1,79 @@ [[_remote_branches]] -=== Remote Branches +=== برنچ‌های ریموت (((branches, remote)))(((references, remote))) -Remote references are references (pointers) in your remote repositories, including branches, tags, and so on. -You can get a full list of remote references explicitly with `git ls-remote [remote]`, or `git remote show [remote]` for remote branches as well as more information. -Nevertheless, a more common way is to take advantage of remote-tracking branches. - -Remote-tracking branches are references to the state of remote branches. -They're local references that you can't move; Git moves them for you whenever you do any network communication, to make sure they accurately represent the state of the remote repository. -Think of them as bookmarks, to remind you where the branches in your remote repositories were the last time you connected to them. - -Remote-tracking branches take the form `/`. -For instance, if you wanted to see what the `master` branch on your `origin` remote looked like as of the last time you communicated with it, you would check the `origin/master` branch. -If you were working on an issue with a partner and they pushed up an `iss53` branch, you might have your own local `iss53` branch, but the branch on the server would be represented by the remote-tracking branch `origin/iss53`. - -This may be a bit confusing, so let's look at an example. -Let's say you have a Git server on your network at `git.ourcompany.com`. -If you clone from this, Git's `clone` command automatically names it `origin` for you, pulls down all its data, creates a pointer to where its `master` branch is, and names it `origin/master` locally. -Git also gives you your own local `master` branch starting at the same place as origin's `master` branch, so you have something to work from. +مراجع یا رفرنس‌های ریموت (Remote/دوردست)، مراجع (نشانگرهایی) در مخزن ریموت شما هستند که شامل برنچ‌ها، تگ‌ها و غیره می‌شود. +شما می‌توانید لیست کاملی از مراجع ریموت را با `git ls-remote ` یا `git remote show ` (برای برنچ‌های ریموت و اطلاعات بیشتر) مشاهده کنید. +گرچه شایان ذکر است که روش رایج‌تر استفاده از برنچ‌های درپی-ریموت (Remote-tracking) است. + +برنچ‌های درپی-ریموت، رفرنس‌هایی به وضعیت برنچ‌های ریموت هستند. +آنها رفرنس‌های محلی هستند که نمی‌توانید جابه‌جا کنید؛ هر گاه که هر ارتباط شبکه‌ای برقرار کنید، گیت آنها را برای شما جابه‌جا می‌کند تا از اینکه آنها به دقت وضعیت مخزن +ریموت را بازنمایی می‌کنند، اطمینان حاصل کند. +می‌توانید به آنها مثل بوک‌مارک بنگرید که به شما یادآوری می‌کنند که آخرین بار که به مخزن‌های ریموت وصل شدید، برنچ‌ها کجا قرار داشته‌اند. + +نام برنچ‌های در پی ریموت به این صورت شکل می‌گیرد: `/`. +به طور مثال اگر می‌خواهید ببینید آخرین بار که با ریموت `origin` ارتباطی داشته‌اید برنچ `master` کجا قرار داشته، باید به بررسی برنچ `origin/master` بپردازید. +با همکاری روی یک ایشو کار می‌کرده‌اید و آنها روی برنچ `iss53` پوش کرده‌اند و ممکن است که شما هم برنچ `iss53` محلی خودتان را داشته باشید. +در این حالت برنچ روی سرور با برنچ درپی-ریموت `origin/iss53` به نمایش در می‌آید. + +این مسئله کمی گیج‌کننده است، پس بیایید به یک مثال نگاهی بیاندازیم. +فرض کنیم که یک سرور گیت به آدرس `git.ourcompany.com` روی شبکهٔ خود دارید. +اگر از این آدرس کلون کنید، دستور `clone` گیت به طور خودکار آنرا `origin` برای شما نامگذاری می‌کند، تمام اطلاعاتش را پول می‌کند، نشانگری به جایی که برنچ `master` است می‌سازد و +نام آنرا `origin/master` می‌‌گذارد. +علاوه بر این گیت به شما برنچ محلی `master` خودتان را می‌دهد که از همان‌جایی که برنچ `master` در origin قرار دارد شروع می‌شود، تا بتوانید روی آن کار کنید. [NOTE] -.``origin'' is not special +.``origin'' چیز خاصی نیست ==== -Just like the branch name ``master'' does not have any special meaning in Git, neither does ``origin''. -While ``master'' is the default name for a starting branch when you run `git init` which is the only reason it's widely used, ``origin'' is the default name for a remote when you run `git clone`. -If you run `git clone -o booyah` instead, then you will have `booyah/master` as your default remote branch.(((origin))) +دقیقاً همانگونه که نام برنچ ``master'' هیچ معنی خاصی در گیت ندارد، ``origin'' هم بی‌معناست. +``master'' نام پیش‌فرض یک برنچ آغازین به هنگام اجرای `git init` است و تنها به همین دلیل بسیار مورد استفاده قرار می‌گیرد. +درست به همان شکل، ``origin'' نام پیش‌فرض یک ریموت به هنگام اجرای `git clone` است. +اگر `git clone -o booyah` را وارد کنید، آنگاه `booyah/master` را به عنوان برنچ پیش‌فرض ریموت خود خواهید دید.(((origin))) ==== -.Server and local repositories after cloning +.مخازن سرور و محلی بعد از کلون کردن image::images/remote-branches-1.png[Server and local repositories after cloning.] -If you do some work on your local `master` branch, and, in the meantime, someone else pushes to `git.ourcompany.com` and updates its `master` branch, then your histories move forward differently. -Also, as long as you stay out of contact with your origin server, your `origin/master` pointer doesn't move. +اگر روی برنچ `master` محلی خود کار کنید و در همین حین شخص دیگری به `git.ourcompany.com` پوش کند و برنچ `master` مخزن را بروزرسانی کند، آنگاه تاریخچه‌های شما به طور متفاوتی +به جلو حرکت می‌کند. علاوه بر آن تا زمانی که بی‌ارتباط با سرور `origin` باقی بمانید، نشانگر `origin/master` تکان نمی‌خورد. -.Local and remote work can diverge +.کارهای روی مخزن محلی و ریموت می‌تواند دوشاخه شود image::images/remote-branches-2.png[Local and remote work can diverge.] -To synchronize your work, you run a `git fetch origin` command. -This command looks up which server ``origin'' is (in this case, it's `git.ourcompany.com`), fetches any data from it that you don't yet have, and updates your local database, moving your `origin/master` pointer to its new, more up-to-date position. +برا همگام‌سازی کارتان با هر ریموتی، باید دستور `git fetch ` اجرا کنید (در این مورد `git fetch origin`). +این دستور سروری که با نام ``origin'' است را بررسی می‌کند (در این مثال آدرس `git.ourcompany.com`)، اطلاعات جدید را فچ (Fetch/واکشی) می‌کند و پایگاه‌داده محلی را بروز می‌کند که باعث +جابه‌جایی نشانگر `origin/master` به مکان بروزترش می‌شود. -.`git fetch` updates your remote references +.`git fetch` برنچ‌های درپی-ریموت‌تان را به روز می‌کند image::images/remote-branches-3.png[`git fetch` updates your remote references.] -To demonstrate having multiple remote servers and what remote branches for those remote projects look like, let's assume you have another internal Git server that is used only for development by one of your sprint teams. -This server is at `git.team1.ourcompany.com`. -You can add it as a new remote reference to the project you're currently working on by running the `git remote add` command as we covered in <<_git_basics_chapter>>. -Name this remote `teamone`, which will be your shortname for that whole URL. +برای نمایش داشتن چند برنچ و اینکه چه برنچی برای پروژه‌های ریموت در کجا قرار دارد، بیاید فرض کنیم که +شما یک سرور گیت داخلی دیگر دارید که فقط برای توسعه با یکی از اعضای تیم «دور» (Sprint) فعلی شما پاسخگو است. +این سرور در `git.team1.ourcompany.com` قرار دارد. +همانگونه که در <> بررسی شد، می‌توانید با `git remote add` آنرا +به عنوان یک مرجع ریموت جدید به پروژه‌ای که در حال حاضر روی آن کار می‌کنید اضافه کنید. +این ریموت را `teamone` بنامید که مختصری از آدرس کامل ریموت است. -.Adding another server as a remote +.اضافه کردن سروری جدید به عنوان ریموت image::images/remote-branches-4.png[Adding another server as a remote.] -Now, you can run `git fetch teamone` to fetch everything the remote `teamone` server has that you don't have yet. -Because that server has a subset of the data your `origin` server has right now, Git fetches no data but sets a remote-tracking branch called `teamone/master` to point to the commit that `teamone` has as its `master` branch. +اکنون می‌توانید `git fetch teamone` را اجرا کنید تا هرچیزی را که هنوز شما ندارید از سرور ریموت `teamone` واکشی کند. +از آنجایی که اکنون سرور فقط زیرمجموعه‌ای از اطلاعات سرور `origin` را دارد، گیت داده‌ای را واکشی نمی‌کند بلکه یک برنچ درپی-ریموت با نام `teamone/master` می‌سازد که به کامیتی که +`teamone` در `master` خود دارد اشاره می‌کند. -.Remote tracking branch for `teamone/master` +.برنچ درپی-ریموت `teamone/master` image::images/remote-branches-5.png[Remote tracking branch for `teamone/master`.] [[_pushing_branches]] -==== Pushing +==== پوش‌کردن (((pushing))) -When you want to share a branch with the world, you need to push it up to a remote that you have write access to. -Your local branches aren't automatically synchronized to the remotes you write to -- you have to explicitly push the branches you want to share. -That way, you can use private branches for work you don't want to share, and push up only the topic branches you want to collaborate on. +هنگامی که می‌خواهید برنچی را با جهان به اشتراک بگذارید، نیاز دارید آنرا به برنچی در ریموتی که در آن اجازهٔ نوشتن دارید پوش کنید. +برنچ‌های محلی شما به طور خودکار با ریموتی که به آنها بگویید همگام نمی‌شوند -- باید به صراحت، برنچ‌هایی را که می‌خواهید به اشراک بگذارید، به سرور پوش کنید. +از این طریق می‌توانید از برنچ‌های شخصی که برای کار دارید و نمی‌خواهید آنها را به اشتراک بگذارید استفاده کنید و فقط برنچ‌های موضوعی که می‌خواهید روی آنها مشارکت صورت گیرد را پوش کنید. -If you have a branch named `serverfix` that you want to work on with others, you can push it up the same way you pushed your first branch. -Run `git push `:(((git commands, push))) +اگر برنچی با نام `serverfix` داشته باشید که بخواهید روی آن با دیگران مشارکت و همکاری داشته باشید، می‌توانید آنرا به همان طریقی که برنچ اول خود را پوش کردید پوش کنید. +اجرا `git push `:(((git commands, push))) [source,console] ---- @@ -79,26 +87,27 @@ To https://github.com/schacon/simplegit * [new branch] serverfix -> serverfix ---- -This is a bit of a shortcut. -Git automatically expands the `serverfix` branchname out to `refs/heads/serverfix:refs/heads/serverfix`, which means, ``Take my serverfix local branch and push it to update the remote's serverfix branch.'' -We'll go over the `refs/heads/` part in detail in <<_git_internals>>, but you can generally leave it off. -You can also do `git push origin serverfix:serverfix`, which does the same thing -- it says, ``Take my serverfix and make it the remote's serverfix.'' -You can use this format to push a local branch into a remote branch that is named differently. -If you didn't want it to be called `serverfix` on the remote, you could instead run `git push origin serverfix:awesomebranch` to push your local `serverfix` branch to the `awesomebranch` branch on the remote project. +این به نوعی یک میانبر است. +گیت به طور خودکار نام برنچ `serverfix` را به `refs/heads/serverfix:refs/heads/serverfix` گسترش می‌دهد که به معنی عبارت روبرو است: «برنچ محلی `serverfix` من را بگیر و برای بروزرسانی +برنچ `serverfix` ریموت آنرا پوش کن.» +در <> مروری بر بخش `refs/heads/` می‌اندازیم ولی به طور کل می‌توانید آنرا نادیده بگیرید. +همچنین می‌توانید `git push origin serverfix:serverfix` کنید که همان کار را می‌کند -- می‌گوید: «serverfix مرا بگیر و serverfix ریموت قرار بده.» +اگر نمی‌خواهید روی ریموت `serverfix` نامیده شود می‌توانید به جای آن، `git push origin serverfix:awesomebranch` را برای پوش کردن برنچ `serverfix` محلیتان به `aweseomebranch` روی پروژه +ریموت اجرا کنید. [NOTE] -.Don't type your password every time +.هر برا رمز خود را تایپ نکنید ==== -If you're using an HTTPS URL to push over, the Git server will ask you for your username and password for authentication. -By default it will prompt you on the terminal for this information so the server can tell if you're allowed to push. +اگر از یک HTTPS URL برای پوش کردن استفاده می‌کنید، سرور گیت از شما رمز و نام کاربریتان را برای احراز هویت می‌خواهد. +به طور پیش‌فرض در ترمینال به شما آگهی می‌دهد تا این اطلاعات را بخواند تا سرور بتواند تشخیص دهد که شما اجازه دارید پوش کنید یا خیر. -If you don't want to type it every single time you push, you can set up a ``credential cache''. -The simplest is just to keep it in memory for a few minutes, which you can easily set up by running `git config --global credential.helper cache`. +اگر نمی‌خواهید هر بار که پوش می‌کنید آنها را تایپ کنید می‌توانید یک «کش گواهی» انجام دهید. +ساده‌ترین راه برای ذخیرهٔ گواهی در حافظه به مدت چند دقیقه است، که می‌توانید به سادگی با اجرای `git config --global credential.helper cache` آنرا تنظیم کنید. -For more information on the various credential caching options available, see <<_credential_caching>>. +برای اطلاعات بیشتر روی تنظیمات کش‌کردن گواهی‌های مختلف موجود به <> مراجعه کنید. ==== -The next time one of your collaborators fetches from the server, they will get a reference to where the server's version of `serverfix` is under the remote branch `origin/serverfix`: +دفعهٔ بعد که یکی از همکاران شما از سرور فچ می‌کند، یک رفرنس با نام `origin/serverfix` به مکان نسخهٔ `serverfix` سرور دریافت می‌کند: [source,console] ---- @@ -111,11 +120,11 @@ From https://github.com/schacon/simplegit * [new branch] serverfix -> origin/serverfix ---- -It's important to note that when you do a fetch that brings down new remote-tracking branches, you don't automatically have local, editable copies of them. -In other words, in this case, you don't have a new `serverfix` branch -- you only have an `origin/serverfix` pointer that you can't modify. +مهم است که به خاطر داشته باشید که هنگامی فچی می‌کنید که برنچ‌های درپی-ریموت جدیدی را واکشی می‌کند، به طور خودکار یک نسخه قابل ویرایش محلی از آنها را نخواهید داشت. +به بیان دیگر، در این مثال، شما یک برنچ `serverfix` جدید ندارید -- شما فقط یک نشانگر `origin/serverfix` خواهید داشت که قابل ویرایش نیست. -To merge this work into your current working branch, you can run `git merge origin/serverfix`. -If you want your own `serverfix` branch that you can work on, you can base it off your remote-tracking branch: +برای ادغام این کار با برنچ فعال حاضر می‌توانید `git merge origin/serverfix` را اجرا کنید. +اگر می‌خواهید که برنچ `serverfix` خود را داشته باشید تا روی آن کار کنید می‌توانید آنرا از جایی که برنچ درپی-ریموت فعلی هست شروع کنید: [source,console] ---- @@ -124,20 +133,22 @@ Branch serverfix set up to track remote branch serverfix from origin. Switched to a new branch 'serverfix' ---- -This gives you a local branch that you can work on that starts where `origin/serverfix` is. +این کار به شما یک برنچ محلی در جایی که `origin/serverfix` است، می‌دهد که می‌توانید روی آن کار کنید. [[_tracking_branches]] -==== Tracking Branches +==== پیگیری برچ‌ها (((branches, tracking)))(((branches, upstream))) -Checking out a local branch from a remote-tracking branch automatically creates what is called a ``tracking branch'' (and the branch it tracks is called an ``upstream branch''). -Tracking branches are local branches that have a direct relationship to a remote branch. -If you're on a tracking branch and type `git pull`, Git automatically knows which server to fetch from and branch to merge into. -When you clone a repository, it generally automatically creates a `master` branch that tracks `origin/master`. -However, you can set up other tracking branches if you wish -- ones that track branches on other remotes, or don't track the `master` branch. -The simple case is the example you just saw, running `git checkout -b /`. -This is a common enough operation that Git provides the `--track` shorthand: +چک‌اوت کردن یک برنچ محلی از یک برنچ درپی-ریموت به طور خودکار ماهیتی به نام «برنچ پیگیر»(Tracking) می‌سازد +(و برنچی که این برنچ در حال پیگیری آن است «برنچ بالادست»(Upstream/آپ‌ستریم) نامیده می‌شود). +برنچ‌های پیگیر برنچ‌های محلی هستند که رابطهٔ مستقیمی با یک برنچ ریموت دارند. +اگر روی یک برنچ پیگیر باشید و `git pull` را تایپ کنید، گیت به طور خود به خودی می‌داند که از چه سروری فچ کند و با چه برنچی آنرا ادغام کند. + +وقتی یک مخزن را کلون می‌کنید، عموماً به طور خودکار برنچ `master` ساخته می‌شود که پیگیر `origin/master` است. +هرچند شما می‌توانید در صورت تمایل برنچ‌های پیگیر دیگری را نیز راه‌اندازی کنید -- آنهایی که درپی برنچ‌های ریموت‌های دیگر هستند یا آنهایی که برنچ `master` را پیگیری نمی‌کنند. +نمونهٔ سادهٔ آن مثالی است که همین الآن ملاحظه کردید: `git checkout -b /branch>` +این عملیات آنقدر رایج است که گیت اختصار `--track` را هم ارائه می‌کند: [source,console] ---- @@ -146,7 +157,8 @@ Branch serverfix set up to track remote branch serverfix from origin. Switched to a new branch 'serverfix' ---- -In fact, this is so common that there's even a shortcut for that shortcut. If the branch name you're trying to checkout (a) doesn't exist and (b) exactly matches a name on only one remote, Git will create a tracking branch for you: +در حقیقت این کار به حدی رایج است که حتی اختصاری هم برای آن اختصار وجود دارد. +اگر نام برنچی که سعی در چک‌اوت کردن آن دارید (a) وجود ندارد و (b) دقیقاً با نام یک برنچ فقط در یک ریموت تطابق دارد، گیت برنچ پیگیر آنرا برای شما می‌سازد: [source,console] ---- @@ -155,7 +167,7 @@ Branch serverfix set up to track remote branch serverfix from origin. Switched to a new branch 'serverfix' ---- -To set up a local branch with a different name than the remote branch, you can easily use the first version with a different local branch name: +برای راه‌اندازی یک برنچ محلی با نامی متفاوت از برنچ ریموت، می‌توانید به آسانی از نسخه اول دستور با یک نام متفاوت برنچ محلی استفاده کنید: [source,console] ---- @@ -164,9 +176,10 @@ Branch sf set up to track remote branch serverfix from origin. Switched to a new branch 'sf' ---- -Now, your local branch `sf` will automatically pull from `origin/serverfix`. +حال برنچ محلی `sf` شما به طور خودکار از `origin/serverfix` پول می‌کند. -If you already have a local branch and want to set it to a remote branch you just pulled down, or want to change the upstream branch you're tracking, you can use the `-u` or `--set-upstream-to` option to `git branch` to explicitly set it at any time. +اگر از قبل یک برنچ محلی دارید و می‌خواهید که آنرا به یک برنچ ریموت که تازه پول کردید نسبت دهید یا هر گاه که خواستید به طور صریح که می‌خواهید برنچ بالادست برنچ پیگیر +فعلی را تغییر دهید، می‌توانید از آپشن `-u` یا `--set-upstream-to` برای `git branch` استفاده کنید. [source,console] ---- @@ -175,56 +188,58 @@ Branch serverfix set up to track remote branch serverfix from origin. ---- [NOTE] -.Upstream shorthand +.اختصار بالادست ==== -When you have a tracking branch set up, you can reference its upstream branch with the `@{upstream}` or `@{u}` shorthand. -So if you're on the `master` branch and it's tracking `origin/master`, you can say something like `git merge @{u}` instead of `git merge origin/master` if you wish.(((+++@{u}+++)))(((+++@{upstream}+++))) +هنگامی که یک برنچ پیگیر تنظیم شده دارید می‌توانید با اختصار `@{upstream}` یا `@{u}` به آن مراجعه کنید. +بنابراین اگر در برنچ `master` هستید و در پی برنچ `origin/master` هستید، اگر مایلید می‌توانید دستوری مثل `git merge @{u}` را به جای `git merge origin/master` اجرا کنید.(((+++@{u}+++)))(((+++@{upstream}+++))) ==== -If you want to see what tracking branches you have set up, you can use the `-vv` option to `git branch`. -This will list out your local branches with more information including what each branch is tracking and if your local branch is ahead, behind or both. +اگر می‌خواهید بدانید که چه برنچ‌های پیگیری راه‌اندازی کرده‌اید می‌توانید از آپشن `-vv` برای `git branch` استفاده کنید. +این کار تمام برنچ‌های محلی را با اطلاعات بیشتری، از قبیل اینکه هر برنچ پیگیر چه برنچی است و آیا برنچ محلی عقب‌تر، جلو‌تر یا عقب-جلوی برنچ ریموت است، لیست می‌کند. [source,console] ---- $ git branch -vv - iss53 7e424c3 [origin/iss53: ahead 2] forgot the brackets - master 1ae2a45 [origin/master] deploying index fix -* serverfix f8674d9 [teamone/server-fix-good: ahead 3, behind 1] this should do it - testing 5ea463a trying something new + iss53 7e424c3 [origin/iss53: ahead 2] Add forgotten brackets + master 1ae2a45 [origin/master] Deploy index fix +* serverfix f8674d9 [teamone/server-fix-good: ahead 3, behind 1] This should do it + testing 5ea463a Try something new ---- -So here we can see that our `iss53` branch is tracking `origin/iss53` and is ``ahead'' by two, meaning that we have two commits locally that are not pushed to the server. -We can also see that our `master` branch is tracking `origin/master` and is up to date. -Next we can see that our `serverfix` branch is tracking the `server-fix-good` branch on our `teamone` server and is ahead by three and behind by one, meaning that there is one commit on the server we haven't merged in yet and three commits locally that we haven't pushed. -Finally we can see that our `testing` branch is not tracking any remote branch. +در اینجا می‌توان دید که برنچ `iss53` ما پیگیر `origin/iss53` است و دو تا «جلوتر» از آن است، به این معنی که ما دو کامیت محلی داریم که هنوز به سرور پوش نکرده‌ایم. +همچنین می‌توان دید که برنچ `master` ما پیگیر `origin/master` است و بروز می‌باشد. +سپس می‌توان دید که برنچ `serverfix` ما پیگیر برنچ `server-fix-good` روی سرور `teamone` ماست و سه کامیت و جلوتر و یکی عقب‌تر است، به این معنا که یک کامیت روی سرور هست که +ما هنوز آنرا مرج نکرده‌ایم و سه کامیت محلی داریم که آنرا را پوش نکرده‌ایم. +در آخر می‌توان دید که برنچ `testing` ما پیگیر هیچ برنچ ریموتی نیست. -It's important to note that these numbers are only since the last time you fetched from each server. -This command does not reach out to the servers, it's telling you about what it has cached from these servers locally. -If you want totally up to date ahead and behind numbers, you'll need to fetch from all your remotes right before running this. -You could do that like this: +البته بسیار مهم است به خاطر داشته باشید که این ارقام صرفاً از آخرین باری که هر سرور را فچ کرده‌اید مانده‌اند. +همچنین این دستور به سرورها نمی‌رود، فقط به شما چیزی را می‌گیود که از این سرورها کش کرده است. +اگر می‌خواهید تمام اطلاعات بروز باشند باید پیش از اجرای این دستور همهٔ ریموت‌ها را فچ کنید. +بدین شکل می‌توانید این کار را انجام دهید: [source,console] ---- $ git fetch --all; git branch -vv ---- -==== Pulling +==== پول‌کردن (((pulling))) -While the `git fetch` command will fetch down all the changes on the server that you don't have yet, it will not modify your working directory at all. -It will simply get the data for you and let you merge it yourself. -However, there is a command called `git pull` which is essentially a `git fetch` immediately followed by a `git merge` in most cases. -If you have a tracking branch set up as demonstrated in the last section, either by explicitly setting it or by having it created for you by the `clone` or `checkout` commands, `git pull` will look up what server and branch your current branch is tracking, fetch from that server and then try to merge in that remote branch. +مادامی که دستور `git fetch` تمام تغییرات سرور را واکشی می‌کند که شما ندارید، پوشهٔ کاری شما را به هیچ عنوان ویرایش نمی‌کند. +به بیان ساده‌تر اطلاعات را برای شما به دست می‌آورد و به شما اجازه می‌دهد خودتان مرج را انجام دهید. +هرچند دستوری به نام `git pull` وجود دارد که به طور ساده `git fetch` است که در اکثر مواقع مستقیماً پس از آن `git merge` اجرا می‌شود. +اگر آنطور که در بخش قبل اشاره شد، برنچ پیگیری را راه‌اندازی کرده‌اید یا به طور صریح آنرا معرفی کرده‌اید یا گیت آنرا با دستورات `clone` یا `checkout` برای شما ساخته است، +`git pull` به دنبال اینکه چه سرور و برنچی را پیگیری می‌کنید می‌گردد، آن سرور را برای شما فچ می‌کند و سپس سعی در مرج کردن آن برنچ ریموت می‌کند. -Generally it's better to simply use the `fetch` and `merge` commands explicitly as the magic of `git pull` can often be confusing. +عموماً بهتر است که به طور صریح از دو دستور `fetch` و `merge` استفاده کنید چرا که `git pull` غالباً می‌تواند گیج‌کننده واقع شود. [[_delete_branches]] -==== Deleting Remote Branches +==== پاک کردن برنچ‌های ریموت (((branches, deleting remote))) -Suppose you're done with a remote branch – say you and your collaborators are finished with a feature and have merged it into your remote's `master` branch (or whatever branch your stable codeline is in). -You can delete a remote branch using the `--delete` option to `git push`. -If you want to delete your `serverfix` branch from the server, you run the following: +فرض کنید که کارتان با یک برنچ ریموت تمام شده است -- فرض کنیم که شما و همکاران شما کارتان روی یک ویژگی تمام شده و آنرا به برنچ `master` ریموت مرج کرده‌اید (یا هر برنچی که کد باثباتتان در آن است). +شما می‌توانید برنچ ریموت را با آپشن `--delete` دستور `git push` پاک کنید. +اگر می‌خواهید که برنچ `serverfix` خود را از سرور پاک کنید، باید دستور زیر را اجرا کنید: [source,console] ---- @@ -233,5 +248,5 @@ To https://github.com/schacon/simplegit - [deleted] serverfix ---- -Basically all this does is remove the pointer from the server. -The Git server will generally keep the data there for a while until a garbage collection runs, so if it was accidentally deleted, it's often easy to recover. +به طور کل تمام کاری که این دستور می‌کند این است که نشانگر برنچ را از سرور پاک کند. +عموماً سرور گیت تمام داده‌ها را تا زمانی که Grabage Collector اجرا شود نگه‌داری می‌کند، تا اگر اشتباهی این پاک‌سازی رخ داده بود بازیابی آن آسان باشد. diff --git a/book/03-git-branching/sections/workflows.asc b/book/03-git-branching/sections/workflows.asc index 9bf801937..35a0d9efb 100644 --- a/book/03-git-branching/sections/workflows.asc +++ b/book/03-git-branching/sections/workflows.asc @@ -1,63 +1,71 @@ -=== Branching Workflows +=== روند کاری شاخه‌سازی -Now that you have the basics of branching and merging down, what can or should you do with them? -In this section, we'll cover some common workflows that this lightweight branching makes possible, so you can decide if you would like to incorporate it into your own development cycle. +حالا که مبانی شاخه‌سازی و ادغام را می‌دانید،‌ چه کار باید یا می‌توانید با آنها کنید؟ +در این بخش ما چندی از روندهای کاری که این حد سبک از شاخه‌سازی ممکن می‌کند را بررسی می‌کنیم تا شما بتوانید تصمیم بگیرید که در روند توسعه خودتان با آنها می‌خواهید چکار کنید. ==== Long-Running Branches (((branches, long-running))) -Because Git uses a simple three-way merge, merging from one branch into another multiple times over a long period is generally easy to do. -This means you can have several branches that are always open and that you use for different stages of your development cycle; you can merge regularly from some of them into others. +از آنجایی که گیت مرج سه طرفهٔ ساده‌ای استفاده می‌کند، مرج کردن متوالی برنچی به برنچ دیگر عموماً آسان است. +این بدان معناست که می‌توانید چندین برنچ داشته باشید که همیشه باز هستند و از آنها برای بخش‌های مختلف چرخهٔ توسعه خود استفاده کنید؛ +می‌توانید به طور منظم آنها را در هم دیگر ادغام کنید. -Many Git developers have a workflow that embraces this approach, such as having only code that is entirely stable in their `master` branch -- possibly only code that has been or will be released. -They have another parallel branch named `develop` or `next` that they work from or use to test stability -- it isn't necessarily always stable, but whenever it gets to a stable state, it can be merged into `master`. -It's used to pull in topic branches (short-lived branches, like your earlier `iss53` branch) when they're ready, to make sure they pass all the tests and don't introduce bugs. +بسیاری از توسعه‌دهنگان روند کاری دارند که از این رویکرد الهام می‌گیرد، مثلاً در برنچ `master` خود فقط کدهای تماماً پایدار را نگه‌داری می‌کنند -- +که احتمالاً فقط کدی است که یا منتشر شده است یا منتشر خواهد شد. + همچنین احتمالاً آنها برنچی موازی هم با نام `develop` یا `next` دارند که روی آن کار می‌کنند یا از آن برای تست ثبات استفاده می‌کنند -- این برنچ لزوماً همیشه باثبات نیست لکن + هنگامی که باثبات می‌شود در `master` مرج می‌شود. + این برنچ برای پول کردن برنچ‌های موضوعی آماده استفاده می‌شود (برنچ‌های کوتاه عمری مانند `iss53` قبل‌تر) تا از اینکه آنها آماده هستند اطمینان حاصل شود که همهٔ تست‌ها روی + پول‌ها انجام می‌شود و باگی تولید نمی‌کنند. -In reality, we're talking about pointers moving up the line of commits you're making. -The stable branches are farther down the line in your commit history, and the bleeding-edge branches are farther up the history. +در حقیقت ما دربارهٔ نشانگرهایی که در خطوط کامیت‌های تولیدی شما حرکت می‌کنند حرف می‌زنیم. +برنچ باثبات معمولاً بسیار پایین‌تر در تاریخچهٔ کامیت‌های شما هستند و برنچ‌های بروز (Bleeding-edge) بسیار بالاتر در تاریخچه قرار دارند. -.A linear view of progressive-stability branching +.دیدگاهی خطی به شاخه‌سازی ثبات-مترقی image::images/lr-branches-1.png[A linear view of progressive-stability branching.] -It's generally easier to think about them as work silos, where sets of commits graduate to a more stable silo when they're fully tested. +به طور کل آسان‌تر است که به برنچ‌ها به عنوان سیلوهای کار نگاه کنیم. جایی که وقتی مجموعه‌ای از کامیت‌ها کاملاً تست شدند به سمت سیلویی باثبات‌تر انتقال داده می‌شوند. [[lrbranch_b]] -.A ``silo'' view of progressive-stability branching +.دیدگاهی ``سیلو'' محور به شاخه‌سازی ثبات-مترقی image::images/lr-branches-2.png[A ``silo'' view of progressive-stability branching.] -You can keep doing this for several levels of stability. -Some larger projects also have a `proposed` or `pu` (proposed updates) branch that has integrated branches that may not be ready to go into the `next` or `master` branch. -The idea is that your branches are at various levels of stability; when they reach a more stable level, they're merged into the branch above them. -Again, having multiple long-running branches isn't necessary, but it's often helpful, especially when you're dealing with very large or complex projects. +شما می‌توانید این فرآیند را برای چند مرحله از ثبات تکرار کنید. +بعضی از پروژه‌های بزرگ‌تر همچنین برنچ `pu` یا `proposed` (بروزرسانی پیشنهادی) دارند که مجتمعی از برنچ‌هایی است که ممکن است هنوز برای راه یافتن به برنچ `master` یا `next` آماده نباشند. +ایدهٔ کلی این است که برنچ‌های شما در مرتبه‌های مختلف ثبات هستند؛ وقتی به مرتبهٔ بالاتری از ثبات رسیدند، به برنچی که در مرتبهٔ بالاتر است مرج خواهند شد. +شایان ذکر است که داشتن چندین برنچ‌ها فعال همزمان لزومی ندارد، اما اغلب مفید واقع می‌شود، به خصوص وقتی که با پروژه‌های خیلی بزرگ یا پیچیده سروکار دارید. [[_topic_branch]] -==== Topic Branches +==== برنچ‌های موضوعی (((branches, topic))) -Topic branches, however, are useful in projects of any size. -A topic branch is a short-lived branch that you create and use for a single particular feature or related work. -This is something you've likely never done with a VCS before because it's generally too expensive to create and merge branches. -But in Git it's common to create, work on, merge, and delete branches several times a day. - -You saw this in the last section with the `iss53` and `hotfix` branches you created. -You did a few commits on them and deleted them directly after merging them into your main branch. -This technique allows you to context-switch quickly and completely -- because your work is separated into silos where all the changes in that branch have to do with that topic, it's easier to see what has happened during code review and such. -You can keep the changes there for minutes, days, or months, and merge them in when they're ready, regardless of the order in which they were created or worked on. - -Consider an example of doing some work (on `master`), branching off for an issue (`iss91`), working on it for a bit, branching off the second branch to try another way of handling the same thing (`iss91v2`), going back to your `master` branch and working there for a while, and then branching off there to do some work that you're not sure is a good idea (`dumbidea` branch). -Your commit history will look something like this: - -.Multiple topic branches +از سوی دیگر برنچ‌های موضوعی در پروژه‌هایی با هر اندازه‌ای مفید هستند. +یک برنچ موضوعی، برنچی کم عمر است که مختص یک کار یا ویژگی خاص می‌سازید و استفاده می‌کنید. +این کاری است که به احتمال خیلی زیاد هرگز در هیچ VCS دیگر انجام نداده‌اید چرا که به طور کل هزینهٔ ساخت و ادغام برنچ‌ها زیاد است. +لکن در گیت ساختن، ادغام، پاک‌کردن و کار کردن روزانهٔ برنچ‌ها رایج است. + +شما در بخش قبل هنگام کار با برنچ‌های `iss53` و `hotfix` که ساختید متوجه این شده‌اید. +شما تعدادی کامیت روی آنها ساختید و آنها را به محض ادغام با برنچ اصلیتان پاک کردید. +این روش به شما این امکان را می‌دهد که سریعاً و تماماً محتوای کاری را تغییر دهید -- به دلیل اینکه کارهای شما به طور مجزا در سیلوهایی است که تمام تغییراتی که در آن +اعمال می‌شود باید مرتبط با موضوع کار باشد، بسیار آسانتر می‌توان از وقایع مرتبط مانند اینکه چه اتفاقی حین بازبینی کد اتفاق افتاده مطلع شد. +شما می‌توانید تغییرات خود را در این سیلوها برای دقایق، روزها و یا ماه‌ها نگه‌داری کنید و وقتی که آماده بودند آنها را بی‌توجه به ترتیب کاری یا پیدایش آنها ادغام کنید. + +شرایطی را تصور کنید که در حال کار کردن هستید (روی `master`)، برای یک ایشو یک برنچ می‌سازید (`iss91`)، کمی روی آن کار می‌کنید؛ برنچ دومی را می‌سازید تا همان مسئله را +به صورت دیگری حل کنید (`iss91v2`)، به برنچ `master` باز می‌گردید و آنجا کمی فعالیت می‌کنید و سپس یک برنچ دیگر می‌سازید تا کمی روی ایده‌ای که از کارکردش مطمئن نیستید کار کنید (برنچ `dumbidea`). +تایخچهٔ کامیت‌هایتان این شکلی به نظر می‌رسد: + +.برنچ‌های چند موضوع image::images/topic-branches-1.png[Multiple topic branches.] -Now, let's say you decide you like the second solution to your issue best (`iss91v2`); and you showed the `dumbidea` branch to your coworkers, and it turns out to be genius. -You can throw away the original `iss91` branch (losing commits `C5` and `C6`) and merge in the other two. -Your history then looks like this: +حال فرض کنیم که فکر می‌کنید راه حل دوم بهترین راه حل برای این مشکل است (`iss91v2`)؛ و برنچ `dumbidea` را نیز به همکارتان نشان داده‌اید و بسیار هوشمندانه به نظر رسیده است. +شما می‌توانید برنچ `iss91` را حذف کنید (کامیت‌های `C5` و `C6` را از دست می‌دهید) و دو برنچ دیگر را ادغام می‌کنید. +پس از این تاریخچهٔ شما بدین شکل خواهد بود: -.History after merging `dumbidea` and `iss91v2` +.تاریخچهٔ پس از ادغام `dumbidea` و `iss91v2` image::images/topic-branches-2.png[History after merging `dumbidea` and `iss91v2`.] -We will go into more detail about the various possible workflows for your Git project in <<_distributed_git>>, so before you decide which branching scheme your next project will use, be sure to read that chapter. +در <> به جزئیات بیشتر دربارهٔ روندهای کاری متفاوت برای پروژه گیتتان می‌پردازیم. +بنابراین پیش از اینکه تصمیم بگیرید برای پروژه آینده خود چه ساختار شاخه‌سازی می‌خواهید، مطمئن باشید که آن فصل را مطالعه کرده‌اید. + -It's important to remember when you're doing all this that these branches are completely local. -When you're branching and merging, everything is being done only in your Git repository -- no server communication is happening. +مهم است به خاطر داشته باشید که هنگامی که تمام این کارها انجام می‌شود، تمام برنچ‌ها تماماً محلی هستند. +وقتی شاخه‌سازی یا مرج می‌کنید، همه چیز فقط در مخزن گیت شما اتفاق می‌افتد -- ارتباطی با سرور برقرار نیست. diff --git a/book/04-git-server/sections/generating-ssh-key.asc b/book/04-git-server/sections/generating-ssh-key.asc index 8dbf7291c..6ed59b1f3 100644 --- a/book/04-git-server/sections/generating-ssh-key.asc +++ b/book/04-git-server/sections/generating-ssh-key.asc @@ -2,7 +2,7 @@ === Generating Your SSH Public Key (((SSH keys))) -That being said, many Git servers authenticate using SSH public keys. +Many Git servers authenticate using SSH public keys. In order to provide a public key, each user in your system must generate one if they don't already have one. This process is similar across all operating systems. First, you should check to make sure you don't already have a key. @@ -18,12 +18,12 @@ config id_dsa.pub ---- You're looking for a pair of files named something like `id_dsa` or `id_rsa` and a matching file with a `.pub` extension. -The `.pub` file is your public key, and the other file is your private key. -If you don't have these files (or you don't even have a `.ssh` directory), you can create them by running a program called `ssh-keygen`, which is provided with the SSH package on Linux/Mac systems and comes with Git for Windows: +The `.pub` file is your public key, and the other file is the corresponding private key. +If you don't have these files (or you don't even have a `.ssh` directory), you can create them by running a program called `ssh-keygen`, which is provided with the SSH package on Linux/macOS systems and comes with Git for Windows: [source,console] ---- -$ ssh-keygen +$ ssh-keygen -o Generating public/private rsa key pair. Enter file in which to save the key (/home/schacon/.ssh/id_rsa): Created directory '/home/schacon/.ssh'. @@ -36,6 +36,8 @@ d0:82:24:8e:d7:f1:bb:9b:33:53:96:93:49:da:9b:e3 schacon@mylaptop.local ---- First it confirms where you want to save the key (`.ssh/id_rsa`), and then it asks twice for a passphrase, which you can leave empty if you don't want to type a password when you use the key. +However, if you do use a password, make sure to add the `-o` option; it saves the private key in a format that is more resistant to brute-force password cracking than is the default format. +You can also use the `ssh-agent` tool to prevent having to enter the password each time. Now, each user that does this has to send their public key to you or whoever is administrating the Git server (assuming you're using an SSH server setup that requires public keys). All they have to do is copy the contents of the `.pub` file and email it. diff --git a/book/04-git-server/sections/git-daemon.asc b/book/04-git-server/sections/git-daemon.asc index d8ed8872e..1bc425770 100644 --- a/book/04-git-server/sections/git-daemon.asc +++ b/book/04-git-server/sections/git-daemon.asc @@ -52,40 +52,6 @@ Also, check that the Git binary is indeed located at `/usr/bin/git` and change t Finally, you'll run `systemctl enable git-daemon` to automatically start the service on boot, and can start and stop the service with, respectively, `systemctl start git-daemon` and `systemctl stop git-daemon`. -Until LTS 14.04, Ubuntu used upstart service unit configuration. -Therefore, on Ubuntu <= 14.04 you can use an Upstart script. -So, in the following file - -[source,console] ----- -/etc/init/local-git-daemon.conf ----- - -you put this script: - -[source,console] ----- -start on startup -stop on shutdown -exec /usr/bin/git daemon \ - --user=git --group=git \ - --reuseaddr \ - --base-path=/srv/git/ \ - /srv/git/ -respawn ----- - -For security reasons, it is strongly encouraged to have this daemon run as a user with read-only permissions to the repositories -- you can easily do this by creating a new user 'git-ro' and running the daemon as them. -For the sake of simplicity we'll simply run it as the same 'git' user that `git-shell` is running as. - -When you restart your machine, your Git daemon will start automatically and respawn if it goes down. -To get it running without having to reboot, you can run this: - -[source,console] ----- -$ initctl start local-git-daemon ----- - On other systems, you may want to use `xinetd`, a script in your `sysvinit` system, or something else -- as long as you get that command daemonized and watched somehow. Next, you have to tell Git which repositories to allow unauthenticated Git server-based access to. diff --git a/book/04-git-server/sections/git-on-a-server.asc b/book/04-git-server/sections/git-on-a-server.asc index b2a7d2c50..18727c660 100644 --- a/book/04-git-server/sections/git-on-a-server.asc +++ b/book/04-git-server/sections/git-on-a-server.asc @@ -5,7 +5,7 @@ Now we'll cover setting up a Git service running these protocols on your own ser [NOTE] ==== -Here we'll be demonstrating the commands and steps needed to do basic, simplified installations on a Linux-based server, though it's also possible to run these services on Mac or Windows servers. +Here we'll be demonstrating the commands and steps needed to do basic, simplified installations on a Linux-based server, though it's also possible to run these services on macOS or Windows servers. Actually setting up a production server within your infrastructure will certainly entail differences in security measures or operating system tools, but hopefully this will give you the general idea of what's involved. ==== @@ -54,7 +54,8 @@ $ git clone user@git.example.com:/srv/git/my_project.git If a user SSHs into a server and has write access to the `/srv/git/my_project.git` directory, they will also automatically have push access. -Git will automatically add group write permissions to a repository properly if you run the `git init` command with the `--shared` option.(((git commands, init, bare))) +Git will automatically add group write permissions to a repository properly if you run the `git init` command with the `--shared` option. +Note that by running this command, you will not destroy any commits, refs, etc. in the process.(((git commands, init, bare))) [source,console] ---- @@ -90,9 +91,9 @@ We assume that if you have a server with which to do this, you already have an S There are a few ways you can give access to everyone on your team. The first is to set up accounts for everybody, which is straightforward but can be cumbersome. -You may not want to run `adduser` and set temporary passwords for every user. +You may not want to run `adduser` (or the possible alternative `useradd`) and have to set temporary passwords for every new user. -A second method is to create a single 'git' user account on the machine, ask every user who is to have write access to send you an SSH public key, and add that key to the `~/.ssh/authorized_keys` file of that new account. +A second method is to create a single 'git' user account on the machine, ask every user who is to have write access to send you an SSH public key, and add that key to the `~/.ssh/authorized_keys` file of that new 'git' account. At that point, everyone will be able to access that machine via the 'git' account. This doesn't affect the commit data in any way -- the SSH user you connect as doesn't affect the commits you've recorded. diff --git a/book/04-git-server/sections/gitlab.asc b/book/04-git-server/sections/gitlab.asc index 5d42b5fc4..a17d0e5d0 100644 --- a/book/04-git-server/sections/gitlab.asc +++ b/book/04-git-server/sections/gitlab.asc @@ -39,7 +39,7 @@ image::images/gitlab-menu.png[The ``Admin area'' item in the GitLab menu.] Users in GitLab are accounts that correspond to people. User accounts don't have a lot of complexity; mainly it's a collection of personal information attached to login data. Each user account comes with a *namespace*, which is a logical grouping of projects that belong to that user. -If the user +jane+ had a project named +project+, that project's url would be http://server/jane/project[]. +If the user +jane+ had a project named +project+, that project's url would be `http://server/jane/project`. [[gitlab_users]] .The GitLab user administration screen. @@ -56,7 +56,7 @@ This is obviously a much more permanent and destructive action, and its uses are ===== Groups A GitLab group is an assemblage of projects, along with data about how users can access those projects. -Each group has a project namespace (the same way that users do), so if the group +training+ has a project +materials+, its url would be http://server/training/materials[]. +Each group has a project namespace (the same way that users do), so if the group +training+ has a project +materials+, its url would be `http://server/training/materials`. [[gitlab_groups]] .The GitLab group administration screen. diff --git a/book/04-git-server/sections/hosted.asc b/book/04-git-server/sections/hosted.asc index e9b8b06f2..6828f64e5 100644 --- a/book/04-git-server/sections/hosted.asc +++ b/book/04-git-server/sections/hosted.asc @@ -7,4 +7,4 @@ Even if you set up and run your own server internally, you may still want to use These days, you have a huge number of hosting options to choose from, each with different advantages and disadvantages. To see an up-to-date list, check out the GitHosting page on the main Git wiki at https://git.wiki.kernel.org/index.php/GitHosting[] -We'll cover using GitHub in detail in <<_github>>, as it is the largest Git host out there and you may need to interact with projects hosted on it in any case, but there are dozens more to choose from should you not want to set up your own Git server. +We'll cover using GitHub in detail in <>, as it is the largest Git host out there and you may need to interact with projects hosted on it in any case, but there are dozens more to choose from should you not want to set up your own Git server. diff --git a/book/04-git-server/sections/protocols.asc b/book/04-git-server/sections/protocols.asc index 3ed8eb762..6fbb41e83 100644 --- a/book/04-git-server/sections/protocols.asc +++ b/book/04-git-server/sections/protocols.asc @@ -7,7 +7,7 @@ Here we'll discuss what they are and in what basic circumstances you would want (((protocols, local))) The most basic is the _Local protocol_, in which the remote repository is in another directory on the same host. -This is often used if everyone on your team has access to a shared filesystem such as an NFS mount, or in the less likely case that everyone logs in to the same computer. +This is often used if everyone on your team has access to a shared filesystem such as an https://en.wikipedia.org/wiki/Network_File_System[NFS] mount, or in the less likely case that everyone logs in to the same computer. The latter wouldn't be ideal, because all your code repository instances would reside on the same computer, making a catastrophic loss much more likely. If you have a shared mounted filesystem, then you can clone, push to, and pull from a local file-based repository. @@ -29,7 +29,7 @@ $ git clone file:///srv/git/project.git Git operates slightly differently if you explicitly specify `file://` at the beginning of the URL. If you just specify the path, Git tries to use hardlinks or directly copy the files it needs. If you specify `file://`, Git fires up the processes that it normally uses to transfer data over a network, which is generally much less efficient. -The main reason to specify the `file://` prefix is if you want a clean copy of the repository with extraneous references or objects left out -- generally after an import from another VCS or something similar (see <<_git_internals>> for maintenance tasks). +The main reason to specify the `file://` prefix is if you want a clean copy of the repository with extraneous references or objects left out -- generally after an import from another VCS or something similar (see <> for maintenance tasks). We'll use the normal path here because doing so is almost always faster. To add a local repository to an existing Git project, you can run something like this: @@ -46,7 +46,7 @@ Then, you can push to and pull from that remote via your new remote name `local_ The pros of file-based repositories are that they're simple and they use existing file permissions and network access. If you already have a shared filesystem to which your whole team has access, setting up a repository is very easy. You stick the bare repository copy somewhere everyone has shared access to and set the read/write permissions as you would for any other shared directory. -We'll discuss how to export a bare repository copy for this purpose in <<_getting_git_on_a_server>>. +We'll discuss how to export a bare repository copy for this purpose in <>. This is also a nice option for quickly grabbing work from someone else's working repository. If you and a co-worker are working on the same project and they want you to check something out, running a command like `git pull /home/john/project` is often easier than them pushing to a remote server and you subsequently fetching from it. @@ -90,7 +90,7 @@ In fact, for services like GitHub, the URL you use to view the repository online If the server does not respond with a Git HTTP smart service, the Git client will try to fall back to the simpler _Dumb_ HTTP protocol. The Dumb protocol expects the bare Git repository to be served like normal files from the web server. The beauty of Dumb HTTP is the simplicity of setting it up. -Basically, all you have to do is put a bare Git repository under your HTTP document root and set up a specific `post-update` hook, and you're done (See <<_git_hooks>>). +Basically, all you have to do is put a bare Git repository under your HTTP document root and set up a specific `post-update` hook, and you're done (See <>). At that point, anyone who can access the web server under which you put the repository can also clone your repository. To allow read access to your repository over HTTP, do something like this: @@ -113,7 +113,7 @@ $ git clone https://example.com/gitproject.git ---- In this particular case, we're using the `/var/www/htdocs` path that is common for Apache setups, but you can use any static web server -- just put the bare repository in its path. -The Git data is served as basic static files (see the <<_git_internals>> chapter for details about exactly how it's served). +The Git data is served as basic static files (see the <> chapter for details about exactly how it's served). Generally you would either choose to run a read/write Smart HTTP server or simply have the files accessible as read-only in the Dumb manner. It's rare to run a mix of the two services. @@ -129,7 +129,7 @@ It is also a very fast and efficient protocol, similar to the SSH one. You can also serve your repositories read-only over HTTPS, which means you can encrypt the content transfer; or you can go so far as to make the clients use specific signed SSL certificates. -Another nice thing is that HTTPS are such commonly used protocols that corporate firewalls are often set up to allow traffic through these ports. +Another nice thing is that HTTP and HTTPS are such commonly used protocols that corporate firewalls are often set up to allow traffic through their ports. ===== The Cons @@ -138,7 +138,7 @@ Other than that, there is very little advantage that other protocols have over S If you're using HTTP for authenticated pushing, providing your credentials is sometimes more complicated than using keys over SSH. There are, however, several credential caching tools you can use, including Keychain access on macOS and Credential Manager on Windows, to make this pretty painless. -Read <<_credential_caching>> to see how to set up secure HTTP password caching on your system. +Read <> to see how to set up secure HTTP password caching on your system. ==== The SSH Protocol @@ -175,14 +175,14 @@ Last, like the HTTPS, Git and Local protocols, SSH is efficient, making the data The negative aspect of SSH is that it doesn't support anonymous access to your Git repository. If you're using SSH, people _must_ have SSH access to your machine, even in a read-only capacity, which doesn't make SSH conducive to open source projects for which people might simply want to clone your repository to examine it. If you're using it only within your corporate network, SSH may be the only protocol you need to deal with. -If you want to allow anonymous read-only access to your projects and also want to use SSH, you’ll have to set up SSH for you to push over but something else for others to fetch from. +If you want to allow anonymous read-only access to your projects and also want to use SSH, you'll have to set up SSH for you to push over but something else for others to fetch from. ==== The Git Protocol (((protocols, git))) -Next is the Git protocol. +Finally, we have the Git protocol. This is a special daemon that comes packaged with Git; it listens on a dedicated port (9418) that provides a service similar to the SSH protocol, but with absolutely no authentication. -In order for a repository to be served over the Git protocol, you must create a `git-daemon-export-ok` file -- the daemon won't serve a repository without that file in it -- but other than that there is no security. +In order for a repository to be served over the Git protocol, you must create a `git-daemon-export-ok` file -- the daemon won't serve a repository without that file in it -- but, other than that, there is no security. Either the Git repository is available for everyone to clone, or it isn't. This means that there is generally no pushing over this protocol. You can enable push access but, given the lack of authentication, anyone on the internet who finds your project's URL could push to that project. @@ -191,7 +191,7 @@ Suffice it to say that this is rare. ===== The Pros The Git protocol is often the fastest network transfer protocol available. -If you’re serving a lot of traffic for a public project or serving a very large project that doesn't require user authentication for read access, it’s likely that you'll want to set up a Git daemon to serve your project. +If you're serving a lot of traffic for a public project or serving a very large project that doesn't require user authentication for read access, it's likely that you'll want to set up a Git daemon to serve your project. It uses the same data-transfer mechanism as the SSH protocol but without the encryption and authentication overhead. ===== The Cons @@ -200,6 +200,6 @@ The downside of the Git protocol is the lack of authentication. It's generally undesirable for the Git protocol to be the only access to your project. Generally, you'll pair it with SSH or HTTPS access for the few developers who have push (write) access and have everyone else use `git://` for read-only access. It's also probably the most difficult protocol to set up. -It must run its own daemon, which requires `xinetd` configuration or the like, which isn't always a walk in the park. +It must run its own daemon, which requires `xinetd` or `systemd` configuration or the like, which isn't always a walk in the park. It also requires firewall access to port 9418, which isn't a standard port that corporate firewalls always allow. Behind big corporate firewalls, this obscure port is commonly blocked. diff --git a/book/04-git-server/sections/setting-up-server.asc b/book/04-git-server/sections/setting-up-server.asc index e271653d9..bbb082956 100644 --- a/book/04-git-server/sections/setting-up-server.asc +++ b/book/04-git-server/sections/setting-up-server.asc @@ -10,7 +10,7 @@ We also assume you're running a standard Linux distribution like Ubuntu. A good deal of what is described here can be automated by using the `ssh-copy-id` command, rather than manually copying and installing public keys. ==== -First, you create a `git` user and a `.ssh` directory for that user. +First, you create a `git` user account and a `.ssh` directory for that user. [source,console] ---- @@ -67,7 +67,7 @@ If you're running it internally, and you set up DNS for `gitserver` to point to $ cd myproject $ git init $ git add . -$ git commit -m 'initial commit' +$ git commit -m 'Initial commit' $ git remote add origin git@gitserver:/srv/git/project.git $ git push origin master ---- @@ -79,25 +79,25 @@ At this point, the others can clone it down and push changes back up just as eas $ git clone git@gitserver:/srv/git/project.git $ cd project $ vim README -$ git commit -am 'fix for the README file' +$ git commit -am 'Fix for README file' $ git push origin master ---- With this method, you can quickly get a read/write Git server up and running for a handful of developers. You should note that currently all these users can also log into the server and get a shell as the `git` user. -If you want to restrict that, you will have to change the shell to something else in the `passwd` file. +If you want to restrict that, you will have to change the shell to something else in the `/etc/passwd` file. -You can easily restrict the `git` user to only doing Git activities with a limited shell tool called `git-shell` that comes with Git. -If you set this as your `git` user's login shell, then the `git` user can't have normal shell access to your server. -To use this, specify `git-shell` instead of bash or csh for your user's login shell. -To do so, you must first add `git-shell` to `/etc/shells` if it's not already there: +You can easily restrict the `git` user account to only Git-related activities with a limited shell tool called `git-shell` that comes with Git. +If you set this as the `git` user account's login shell, then that account can't have normal shell access to your server. +To use this, specify `git-shell` instead of `bash` or `csh` for that account's login shell. +To do so, you must first add the full pathname of the `git-shell` command to `/etc/shells` if it's not already there: [source,console] ---- -$ cat /etc/shells # see if `git-shell` is already in there. If not... +$ cat /etc/shells # see if git-shell is already in there. If not... $ which git-shell # make sure git-shell is installed on your system. -$ sudo vim /etc/shells # and add the path to git-shell from last command +$ sudo -e /etc/shells # and add the path to git-shell from last command ---- Now you can edit the shell for a user using `chsh -s `: @@ -107,7 +107,7 @@ Now you can edit the shell for a user using `chsh -s `: $ sudo chsh git -s $(which git-shell) ---- -Now, the `git` user can only use the SSH connection to push and pull Git repositories and can't shell onto the machine. +Now, the `git` user can still use the SSH connection to push and pull Git repositories but can't shell onto the machine. If you try, you'll see a login rejection like this: [source,console] @@ -118,6 +118,31 @@ hint: ~/git-shell-commands should exist and have read and execute access. Connection to gitserver closed. ---- +At this point, users are still able to use SSH port forwarding to access any host the git server is able to reach. +If you want to prevent that, you can edit the `authorized_keys` file and prepend the following options to each key you'd like to restrict: + +[source,console] +---- +no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty +---- + +The result should look like this: + +[source,console] +---- +$ cat ~/.ssh/authorized_keys +no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-rsa +AAAAB3NzaC1yc2EAAAADAQABAAABAQCB007n/ww+ouN4gSLKssMxXnBOvf9LGt4LojG6rs6h +PB09j9R/T17/x4lhJA0F3FR1rP6kYBRsWj2aThGw6HXLm9/5zytK6Ztg3RPKK+4kYjh6541N +YsnEAZuXz0jTTyAUfrtU3Z5E003C4oxOj6H0rfIF1kKI9MAQLMdpGW1GYEIgS9EzSdfd8AcC +IicTDWbqLAcU4UpkaX8KyGlLwsNuuGztobF8m72ALC/nLF6JLtPofwFBlgc+myivO7TCUSBd +LQlgMVOFq1I2uPWQOkOWQAHukEOmfjy2jctxSDBQ220ymjaNsHT4kgtZg2AYYgPqdAv8JggJ +ICUvax2T9va5 gsg-keypair + +no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-rsa +AAAAB3NzaC1yc2EAAAADAQABAAABAQDEwENNMomTboYI+LJieaAY16qiXiH3wuvENhBG... +---- + Now Git network commands will still work just fine but the users won't be able to get a shell. As the output states, you can also set up a directory in the `git` user's home directory that customizes the `git-shell` command a bit. For instance, you can restrict the Git commands that the server will accept or you can customize the message that users see if they try to SSH in like that. diff --git a/book/04-git-server/sections/smart-http.asc b/book/04-git-server/sections/smart-http.asc index 43956dda8..60bdd3097 100644 --- a/book/04-git-server/sections/smart-http.asc +++ b/book/04-git-server/sections/smart-http.asc @@ -18,7 +18,7 @@ $ a2enmod cgi alias env This also enables the `mod_cgi`, `mod_alias`, and `mod_env` modules, which are all needed for this to work properly. -You’ll also need to set the Unix user group of the `/srv/git` directories to `www-data` so your web server can read- and write-access the repositories, because the Apache instance running the CGI script will (by default) be running as that user: +You'll also need to set the Unix user group of the `/srv/git` directories to `www-data` so your web server can read- and write-access the repositories, because the Apache instance running the CGI script will (by default) be running as that user: [source,console] ---- @@ -68,5 +68,5 @@ You can do this with nearly any CGI-capable web server, so go with the one that [NOTE] ==== -For more information on configuring authentication in Apache, check out the Apache docs here: http://httpd.apache.org/docs/current/howto/auth.html[] +For more information on configuring authentication in Apache, check out the Apache docs here: https://httpd.apache.org/docs/current/howto/auth.html[] ==== diff --git a/book/05-distributed-git/sections/contributing.asc b/book/05-distributed-git/sections/contributing.asc index 73a4fba33..dc268b611 100644 --- a/book/05-distributed-git/sections/contributing.asc +++ b/book/05-distributed-git/sections/contributing.asc @@ -49,40 +49,42 @@ If you run that command before committing, you can tell if you're about to commi Next, try to make each commit a logically separate changeset. If you can, try to make your changes digestible -- don't code for a whole weekend on five different issues and then submit them all as one massive commit on Monday. Even if you don't commit during the weekend, use the staging area on Monday to split your work into at least one commit per issue, with a useful message per commit. -If some of the changes modify the same file, try to use `git add --patch` to partially stage files (covered in detail in <<_interactive_staging>>). +If some of the changes modify the same file, try to use `git add --patch` to partially stage files (covered in detail in <>). The project snapshot at the tip of the branch is identical whether you do one commit or five, as long as all the changes are added at some point, so try to make things easier on your fellow developers when they have to review your changes. This approach also makes it easier to pull out or revert one of the changesets if you need to later. -<<_rewriting_history>> describes a number of useful Git tricks for rewriting history and interactively staging files -- use these tools to help craft a clean and understandable history before sending the work to someone else. +<> describes a number of useful Git tricks for rewriting history and interactively staging files -- use these tools to help craft a clean and understandable history before sending the work to someone else. The last thing to keep in mind is the commit message. Getting in the habit of creating quality commit messages makes using and collaborating with Git a lot easier. As a general rule, your messages should start with a single line that's no more than about 50 characters and that describes the changeset concisely, followed by a blank line, followed by a more detailed explanation. The Git project requires that the more detailed explanation include your motivation for the change and contrast its implementation with previous behavior -- this is a good guideline to follow. -It's also a good idea to use the imperative present tense in these messages. -In other words, use commands. -Instead of ``I added tests for'' or ``Adding tests for,'' use ``Add tests for.'' -Here is a http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[template originally written by Tim Pope]: +Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." +Here is a https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[template originally written by Tim Pope]: [source,text] ---- -Short (50 chars or less) summary of changes +Capitalized, short (50 chars or less) summary -More detailed explanatory text, if necessary. Wrap it to -about 72 characters or so. In some contexts, the first -line is treated as the subject of an email and the rest of -the text as the body. The blank line separating the -summary from the body is critical (unless you omit the body -entirely); tools like rebase can get confused if you run -the two together. +More detailed explanatory text, if necessary. Wrap it to about 72 +characters or so. In some contexts, the first line is treated as the +subject of an email and the rest of the text as the body. The blank +line separating the summary from the body is critical (unless you omit +the body entirely); tools like rebase can get confused if you run the +two together. + +Write your commit message in the imperative: "Fix bug" and not "Fixed bug" +or "Fixes bug." This convention matches up with commit messages generated +by commands like git merge and git revert. Further paragraphs come after blank lines. - - Bullet points are okay, too +- Bullet points are okay, too + +- Typically a hyphen or asterisk is used for the bullet, followed by a + single space, with blank lines in between, but conventions vary here - - Typically a hyphen or asterisk is used for the bullet, - preceded by a single space, with blank lines in - between, but conventions vary here +- Use a hanging indent ---- If all your commit messages follow this model, things will be much easier for you and the developers with whom you collaborate. @@ -118,8 +120,8 @@ Cloning into 'simplegit'... ... $ cd simplegit/ $ vim lib/simplegit.rb -$ git commit -am 'remove invalid default value' -[master 738ee87] remove invalid default value +$ git commit -am 'Remove invalid default value' +[master 738ee87] Remove invalid default value 1 files changed, 1 insertions(+), 1 deletions(-) ---- @@ -133,8 +135,8 @@ Cloning into 'simplegit'... ... $ cd simplegit/ $ vim TODO -$ git commit -am 'add reset task' -[master fbff5bc] add reset task +$ git commit -am 'Add reset task' +[master fbff5bc] Add reset task 1 files changed, 1 insertions(+), 0 deletions(-) ---- @@ -248,18 +250,18 @@ commit 738ee872852dfaa9d6634e0dea7a324040193016 Author: John Smith Date: Fri May 29 16:01:27 2009 -0700 - remove invalid default value + Remove invalid default value ---- The `issue54..origin/master` syntax is a log filter that asks Git to display only those commits that are on the latter branch (in this case `origin/master`) that are not on the first branch (in this case `issue54`). -We'll go over this syntax in detail in <<_commit_ranges>>. +We'll go over this syntax in detail in <>. From the above output, we can see that there is a single commit that John has made that Jessica has not merged into her local work. If she merges `origin/master`, that is the single commit that will modify her local work. -Now, Jessica can merge her topic work into her master branch, merge John's work (`origin/master`) into her `master` branch, and then push back to the server again. +Now, Jessica can merge her topic work into her `master` branch, merge John's work (`origin/master`) into her `master` branch, and then push back to the server again. -First (having committed all of the work on her `issue54` topic branch), Jessica switches back to her master branch in preparation for integrating all this work: +First (having committed all of the work on her `issue54` topic branch), Jessica switches back to her `master` branch in preparation for integrating all this work: [source,console] ---- @@ -342,8 +344,8 @@ She creates a new branch for the feature and does some work on it there: $ git checkout -b featureA Switched to a new branch 'featureA' $ vim lib/simplegit.rb -$ git commit -am 'add limit to log function' -[featureA 3300904] add limit to log function +$ git commit -am 'Add limit to log function' +[featureA 3300904] Add limit to log function 1 files changed, 1 insertions(+), 1 deletions(-) ---- @@ -375,12 +377,12 @@ Now, Jessica makes a couple of commits on the `featureB` branch: [source,console] ---- $ vim lib/simplegit.rb -$ git commit -am 'made the ls-tree function recursive' -[featureB e5b0fdc] made the ls-tree function recursive +$ git commit -am 'Make ls-tree function recursive' +[featureB e5b0fdc] Make ls-tree function recursive 1 files changed, 1 insertions(+), 1 deletions(-) $ vim lib/simplegit.rb -$ git commit -am 'add ls-files' -[featureB 8512791] add ls-files +$ git commit -am 'Add ls-files' +[featureB 8512791] Add ls-files 1 files changed, 5 insertions(+), 0 deletions(-) ---- @@ -424,7 +426,7 @@ To jessica@githost:simplegit.git ---- This is called a _refspec_. -See <<_refspec>> for a more detailed discussion of Git refspecs and different things you can do with them. +See <> for a more detailed discussion of Git refspecs and different things you can do with them. Also notice the `-u` flag; this is short for `--set-upstream`, which configures the branches for easier pushing and pulling later. Suddenly, Jessica gets email from John, who tells her he's pushed some changes to the `featureA` branch on which they are collaborating, and he asks Jessica to take a look at them. @@ -447,7 +449,7 @@ commit aad881d154acdaeb2b6b18ea0e827ed8a6d671e6 Author: John Smith Date: Fri May 29 19:57:33 2009 -0700 - changed log output to 30 from 25 + Increase log output to 30 from 25 ---- If Jessica likes what she sees, she can merge John's new work into her local `featureA` branch with: @@ -467,8 +469,8 @@ Finally, Jessica might want to make a couple minor changes to all that merged co [source,console] ---- -$ git commit -am 'small tweak' -[featureA 774b3ed] small tweak +$ git commit -am 'Add small tweak to merged content' +[featureA 774b3ed] Add small tweak to merged content 1 files changed, 1 insertions(+), 1 deletions(-) $ git push ... @@ -520,7 +522,7 @@ $ git commit [NOTE] ==== -You may want to use `rebase -i` to squash your work down to a single commit, or rearrange the work in the commits to make the patch easier for the maintainer to review -- see <<_rewriting_history>> for more information about interactive rebasing. +You may want to use `rebase -i` to squash your work down to a single commit, or rearrange the work in the commits to make the patch easier for the maintainer to review -- see <> for more information about interactive rebasing. ==== When your branch work is finished and you're ready to contribute it back to the maintainers, go to the original project page and click the ``Fork'' button, creating your own writable fork of the project. @@ -532,8 +534,8 @@ $ git remote add myfork ---- You then need to push your new work to this repository. -It's easiest to push the topic branch you're working on to your forked repository, rather than merging that work into your master branch and pushing that. -The reason is that if your work isn't accepted or is cherry-picked, you don't have to rewind your master branch (the Git `cherry-pick` operation is covered in more detail in <<_rebase_cherry_pick>>). +It's easiest to push the topic branch you're working on to your forked repository, rather than merging that work into your `master` branch and pushing that. +The reason is that if your work isn't accepted or is cherry-picked, you don't have to rewind your `master` branch (the Git `cherry-pick` operation is covered in more detail in <>). If the maintainers `merge`, `rebase`, or `cherry-pick` your work, you'll eventually get it back via pulling from their repository anyhow. In any event, you can push your work with: @@ -545,7 +547,7 @@ $ git push -u myfork featureA (((git commands, request-pull))) Once your work has been pushed to your fork of the repository, you need to notify the maintainers of the original project that you have work you'd like them to merge. -This is often called a _pull request_, and you typically generate such a request either via the website -- GitHub has its own ``Pull Request'' mechanism that we'll go over in <<_github>> -- or you can run the `git request-pull` command and email the subsequent output to the project maintainer manually. +This is often called a _pull request_, and you typically generate such a request either via the website -- GitHub has its own ``Pull Request'' mechanism that we'll go over in <> -- or you can run the `git request-pull` command and email the subsequent output to the project maintainer manually. The `git request-pull` command takes the base branch into which you want your topic branch pulled and the Git repository URL you want them to pull from, and produces a summary of all the changes you're asking to be pulled. For instance, if Jessica wants to send John a pull request, and she's done two commits on the topic branch she just pushed, she can run this: @@ -554,16 +556,16 @@ For instance, if Jessica wants to send John a pull request, and she's done two c ---- $ git request-pull origin/master myfork The following changes since commit 1edee6b1d61823a2de3b09c160d7080b8d1b3a40: - John Smith (1): - added a new function +Jessica Smith (1): + Create new function are available in the git repository at: git://githost/simplegit.git featureA Jessica Smith (2): - add limit to log function - change log output to 30 from 25 + Add limit to log function + Increase log output to 30 from 25 lib/simplegit.rb | 10 +++++++++- 1 files changed, 9 insertions(+), 1 deletions(-) @@ -662,7 +664,7 @@ The nice thing about this is that applying a patch from an email generated with ---- $ git format-patch -M origin/master 0001-add-limit-to-log-function.patch -0002-changed-log-output-to-30-from-25.patch +0002-increase-log-output-to-30-from-25.patch ---- The `format-patch` command prints out the names of the patch files it creates. @@ -675,7 +677,7 @@ $ cat 0001-add-limit-to-log-function.patch From 330090432754092d704da8e76ca5c05c198e71a8 Mon Sep 17 00:00:00 2001 From: Jessica Smith Date: Sun, 6 Apr 2008 10:17:23 -0700 -Subject: [PATCH 1/2] add limit to log function +Subject: [PATCH 1/2] Add limit to log function Limit log functionality to the first 20 @@ -755,8 +757,8 @@ After this is done, you can use `git send-email` to send your patches: [source,console] ---- $ git send-email *.patch -0001-added-limit-to-log-function.patch -0002-changed-log-output-to-30-from-25.patch +0001-add-limit-to-log-function.patch +0002-increase-log-output-to-30-from-25.patch Who should the emails appear to be from? [Jessica Smith ] Emails will be sent from: Jessica Smith Who should the emails be sent to? jessica@example.com @@ -773,7 +775,7 @@ OK. Log says: Sendmail: /usr/sbin/sendmail -i jessica@example.com From: Jessica Smith To: jessica@example.com -Subject: [PATCH 1/2] added limit to log function +Subject: [PATCH 1/2] Add limit to log function Date: Sat, 30 May 2009 13:29:15 -0700 Message-Id: <1243715356-61726-1-git-send-email-jessica@example.com> X-Mailer: git-send-email 1.6.2.rc1.20.g8c5b.dirty diff --git a/book/05-distributed-git/sections/distributed-workflows.asc b/book/05-distributed-git/sections/distributed-workflows.asc index bc0270a40..4d0164adb 100644 --- a/book/05-distributed-git/sections/distributed-workflows.asc +++ b/book/05-distributed-git/sections/distributed-workflows.asc @@ -1,18 +1,18 @@ === Distributed Workflows (((workflows))) -Unlike Centralized Version Control Systems (CVCSs), the distributed nature of Git allows you to be far more flexible in how developers collaborate on projects. -In centralized systems, every developer is a node working more or less equally on a central hub. -In Git, however, every developer is potentially both a node and a hub -- that is, every developer can both contribute code to other repositories and maintain a public repository on which others can base their work and which they can contribute to. -This opens a vast range of workflow possibilities for your project and/or your team, so we'll cover a few common paradigms that take advantage of this flexibility. +In contrast with Centralized Version Control Systems (CVCSs), the distributed nature of Git allows you to be far more flexible in how developers collaborate on projects. +In centralized systems, every developer is a node working more or less equally with a central hub. +In Git, however, every developer is potentially both a node and a hub; that is, every developer can both contribute code to other repositories and maintain a public repository on which others can base their work and which they can contribute to. +This presents a vast range of workflow possibilities for your project and/or your team, so we'll cover a few common paradigms that take advantage of this flexibility. We'll go over the strengths and possible weaknesses of each design; you can choose a single one to use, or you can mix and match features from each. ==== Centralized Workflow (((workflows, centralized))) In centralized systems, there is generally a single collaboration model -- the centralized workflow. -One central hub, or _repository_, can accept code, and everyone synchronizes their work to it. -A number of developers are nodes -- consumers of that hub -- and synchronize to that one place. +One central hub, or _repository_, can accept code, and everyone synchronizes their work with it. +A number of developers are nodes -- consumers of that hub -- and synchronize with that centralized location. .Centralized workflow. image::images/centralized_workflow.png[Centralized workflow.] @@ -23,6 +23,7 @@ This concept is as true in Git as it is in Subversion(((Subversion))) (or any CV If you are already comfortable with a centralized workflow in your company or team, you can easily continue using that workflow with Git. Simply set up a single repository, and give everyone on your team push access; Git won't let users overwrite each other. + Say John and Jessica both start working at the same time. John finishes his change and pushes it to the server. Then Jessica tries to push her changes, but the server rejects them. @@ -66,11 +67,11 @@ This is a variant of a multiple-repository workflow. It's generally used by huge projects with hundreds of collaborators; one famous example is the Linux kernel. Various integration managers are in charge of certain parts of the repository; they're called _lieutenants_. All the lieutenants have one integration manager known as the benevolent dictator. -The benevolent dictator pushes from his directory to a reference repository from which all the collaborators need to pull. +The benevolent dictator pushes from their directory to a reference repository from which all the collaborators need to pull. The process works like this (see <>): 1. Regular developers work on their topic branch and rebase their work on top of `master`. - The `master` branch is that of the reference directory to which the dictator pushes. + The `master` branch is that of the reference repository to which the dictator pushes. 2. Lieutenants merge the developers' topic branches into their `master` branch. 3. The dictator merges the lieutenants' `master` branches into the dictator's `master` branch. 4. Finally, the dictator pushes that `master` branch to the reference repository so the other developers can rebase on it. diff --git a/book/05-distributed-git/sections/maintaining.asc b/book/05-distributed-git/sections/maintaining.asc index 448cfc534..df1b879a6 100644 --- a/book/05-distributed-git/sections/maintaining.asc +++ b/book/05-distributed-git/sections/maintaining.asc @@ -1,17 +1,17 @@ === Maintaining a Project (((maintaining a project))) -In addition to knowing how to effectively contribute to a project, you'll likely need to know how to maintain one. +In addition to knowing how to contribute effectively to a project, you'll likely need to know how to maintain one. This can consist of accepting and applying patches generated via `format-patch` and emailed to you, or integrating changes in remote branches for repositories you've added as remotes to your project. Whether you maintain a canonical repository or want to help by verifying or approving patches, you need to know how to accept work in a way that is clearest for other contributors and sustainable by you over the long run. ==== Working in Topic Branches (((branches, topic))) -When you're thinking of integrating new work, it's generally a good idea to try it out in a topic branch – a temporary branch specifically made to try out that new work. +When you're thinking of integrating new work, it's generally a good idea to try it out in a _topic branch_ -- a temporary branch specifically made to try out that new work. This way, it's easy to tweak a patch individually and leave it if it's not working until you have time to come back to it. If you create a simple branch name based on the theme of the work you're going to try, such as `ruby_client` or something similarly descriptive, you can easily remember it if you have to abandon it for a while and come back later. -The maintainer of the Git project tends to namespace these branches as well – such as `sc/ruby_client`, where `sc` is short for the person who contributed the work. +The maintainer of the Git project tends to namespace these branches as well -- such as `sc/ruby_client`, where `sc` is short for the person who contributed the work. As you'll remember, you can create the branch based off your `master` branch like this: [source,console] @@ -51,13 +51,13 @@ It's almost identical to running a `patch -p1` command to apply the patch, altho It also handles file adds, deletes, and renames if they're described in the `git diff` format, which `patch` won't do. Finally, `git apply` is an ``apply all or abort all'' model where either everything is applied or nothing is, whereas `patch` can partially apply patchfiles, leaving your working directory in a weird state. `git apply` is overall much more conservative than `patch`. -It won't create a commit for you – after running it, you must stage and commit the changes introduced manually. +It won't create a commit for you -- after running it, you must stage and commit the changes introduced manually. -You can also use `git apply` to see if a patch applies cleanly before you try actually applying it – you can run `git apply --check` with the patch: +You can also use `git apply` to see if a patch applies cleanly before you try actually applying it -- you can run `git apply --check` with the patch: [source,console] ---- -$ git apply --check 0001-seeing-if-this-helps-the-gem.patch +$ git apply --check 0001-see-if-this-helps-the-gem.patch error: patch failed: ticgit.gemspec:1 error: ticgit.gemspec: patch does not apply ---- @@ -82,7 +82,7 @@ It looks something like this: From 330090432754092d704da8e76ca5c05c198e71a8 Mon Sep 17 00:00:00 2001 From: Jessica Smith Date: Sun, 6 Apr 2008 10:17:23 -0700 -Subject: [PATCH 1/2] add limit to log function +Subject: [PATCH 1/2] Add limit to log function Limit log functionality to the first 20 ---- @@ -96,7 +96,7 @@ However, if someone uploaded a patch file generated via `git format-patch` to a [source,console] ---- $ git am 0001-limit-log-function.patch -Applying: add limit to log function +Applying: Add limit to log function ---- You can see that it applied cleanly and automatically created the new commit for you. @@ -112,7 +112,7 @@ AuthorDate: Sun Apr 6 10:17:23 2008 -0700 Commit: Scott Chacon CommitDate: Thu Apr 9 09:19:06 2009 -0700 - add limit to log function + Add limit to log function Limit log functionality to the first 20 ---- @@ -126,8 +126,8 @@ In that case, the `git am` process will fail and ask you what you want to do: [source,console] ---- -$ git am 0001-seeing-if-this-helps-the-gem.patch -Applying: seeing if this helps the gem +$ git am 0001-see-if-this-helps-the-gem.patch +Applying: See if this helps the gem error: patch failed: ticgit.gemspec:1 error: ticgit.gemspec: patch does not apply Patch failed at 0001. @@ -137,24 +137,24 @@ To restore the original branch and stop patching run "git am --abort". ---- This command puts conflict markers in any files it has issues with, much like a conflicted merge or rebase operation. -You solve this issue much the same way – edit the file to resolve the conflict, stage the new file, and then run `git am --resolved` to continue to the next patch: +You solve this issue much the same way -- edit the file to resolve the conflict, stage the new file, and then run `git am --resolved` to continue to the next patch: [source,console] ---- $ (fix the file) $ git add ticgit.gemspec $ git am --resolved -Applying: seeing if this helps the gem +Applying: See if this helps the gem ---- If you want Git to try a bit more intelligently to resolve the conflict, you can pass a `-3` option to it, which makes Git attempt a three-way merge. This option isn't on by default because it doesn't work if the commit the patch says it was based on isn't in your repository. -If you do have that commit – if the patch was based on a public commit – then the `-3` option is generally much smarter about applying a conflicting patch: +If you do have that commit -- if the patch was based on a public commit -- then the `-3` option is generally much smarter about applying a conflicting patch: [source,console] ---- -$ git am -3 0001-seeing-if-this-helps-the-gem.patch -Applying: seeing if this helps the gem +$ git am -3 0001-see-if-this-helps-the-gem.patch +Applying: See if this helps the gem error: patch failed: ticgit.gemspec:1 error: ticgit.gemspec: patch does not apply Using index info to reconstruct a base tree... @@ -172,7 +172,7 @@ If you're applying a number of patches from an mbox, you can also run the `am` c $ git am -3 -i mbox Commit Body is: -------------------------- -seeing if this helps the gem +See if this helps the gem -------------------------- Apply? [y]es/[n]o/[e]dit/[v]iew patch/[a]ccept all ---- @@ -201,7 +201,7 @@ If she emails you again later with another branch containing another great featu This is most useful if you're working with a person consistently. If someone only has a single patch to contribute once in a while, then accepting it over email may be less time consuming than requiring everyone to run their own server and having to continually add and remove remotes to get a few patches. You're also unlikely to want to have hundreds of remotes, each for someone who contributes only a patch or two. -However, scripts and hosted services may make this easier – it depends largely on how you develop and how your contributors develop. +However, scripts and hosted services may make this easier -- it depends largely on how you develop and how your contributors develop. The other advantage of this approach is that you get the history of the commits as well. Although you may have legitimate merge issues, you know where in your history their work is based; a proper three-way merge is the default rather than having to supply a `-3` and hope the patch was generated off a public commit to which you have access. @@ -225,8 +225,8 @@ Now you have a topic branch that contains contributed work. At this point, you can determine what you'd like to do with it. This section revisits a couple of commands so you can see how you can use them to review exactly what you'll be introducing if you merge this into your main branch. -It's often helpful to get a review of all the commits that are in this branch but that aren't in your master branch. -You can exclude commits in the master branch by adding the `--not` option before the branch name. +It's often helpful to get a review of all the commits that are in this branch but that aren't in your `master` branch. +You can exclude commits in the `master` branch by adding the `--not` option before the branch name. This does the same thing as the `master..contrib` format that we used earlier. For example, if your contributor sends you two patches and you create a branch called `contrib` and applied those patches there, you can run this: @@ -237,13 +237,13 @@ commit 5b6235bd297351589efc4d73316f0a68d484f118 Author: Scott Chacon Date: Fri Oct 24 09:53:59 2008 -0700 - seeing if this helps the gem + See if this helps the gem commit 7482e0d16d04bea79d0dba8988cc78df655f16a0 Author: Scott Chacon Date: Mon Oct 22 19:38:36 2008 -0700 - updated the gemspec to hopefully work better + Update gemspec to hopefully work better ---- To see what changes each commit introduces, remember that you can pass the `-p` option to `git log` and it will append the diff introduced to each commit. @@ -263,8 +263,8 @@ For example, if you've added a line in a file on the `master` branch, a direct c If `master` is a direct ancestor of your topic branch, this isn't a problem; but if the two histories have diverged, the diff will look like you're adding all the new stuff in your topic branch and removing everything unique to the `master` branch. -What you really want to see are the changes added to the topic branch -- the work you'll introduce if you merge this branch with master. -You do that by having Git compare the last commit on your topic branch with the first common ancestor it has with the master branch. +What you really want to see are the changes added to the topic branch -- the work you'll introduce if you merge this branch with `master`. +You do that by having Git compare the last commit on your topic branch with the first common ancestor it has with the `master` branch. Technically, you can do that by explicitly figuring out the common ancestor and then running your diff on it: @@ -290,7 +290,7 @@ In the context of the `git diff` command, you can put three periods after anothe $ git diff master...contrib ---- -This command shows you only the work your current topic branch has introduced since its common ancestor with master. +This command shows you only the work your current topic branch has introduced since its common ancestor with `master`. That is a very useful syntax to remember. ==== Integrating Contributed Work @@ -363,14 +363,15 @@ image::images/large-merges-2.png[Merging contributed topic branches into long-te When a topic branch has finally been merged into `master`, it's removed from the repository. The Git project also has a `maint` branch that is forked off from the last release to provide backported patches in case a maintenance release is required. Thus, when you clone the Git repository, you have four branches that you can check out to evaluate the project in different stages of development, depending on how cutting edge you want to be or how you want to contribute; and the maintainer has a structured workflow to help them vet new contributions. -The Git project's workflow is specialized. To clearly understand this you could check out the https://github.com/git/git/blob/master/Documentation/howto/maintain-git.txt[Git Maintainer's guide]. +The Git project's workflow is specialized. +To clearly understand this you could check out the https://github.com/git/git/blob/master/Documentation/howto/maintain-git.txt[Git Maintainer's guide]. [[_rebase_cherry_pick]] ===== Rebasing and Cherry-Picking Workflows (((workflows, rebasing and cherry-picking))) -Other maintainers prefer to rebase or cherry-pick contributed work on top of their master branch, rather than merging it in, to keep a mostly linear history. -When you have work in a topic branch and have determined that you want to integrate it, you move to that branch and run the rebase command to rebuild the changes on top of your current master (or `develop`, and so on) branch. +Other maintainers prefer to rebase or cherry-pick contributed work on top of their `master` branch, rather than merging it in, to keep a mostly linear history. +When you have work in a topic branch and have determined that you want to integrate it, you move to that branch and run the rebase command to rebuild the changes on top of your current `master` (or `develop`, and so on) branch. If that works well, you can fast-forward your `master` branch, and you'll end up with a linear project history. (((git commands, cherry-pick))) @@ -383,7 +384,7 @@ For example, suppose you have a project that looks like this: .Example history before a cherry-pick. image::images/rebasing-1.png[Example history before a cherry-pick.] -If you want to pull commit `e43a6` into your master branch, you can run +If you want to pull commit `e43a6` into your `master` branch, you can run [source,console] ---- @@ -406,7 +407,7 @@ Now you can remove your topic branch and drop the commits you didn't want to pul (((git commands, rerere)))(((rerere))) If you're doing lots of merging and rebasing, or you're maintaining a long-lived topic branch, Git has a feature called ``rerere'' that can help. -Rerere stands for ``reuse recorded resolution'' – it's a way of shortcutting manual conflict resolution. +Rerere stands for ``reuse recorded resolution'' -- it's a way of shortcutting manual conflict resolution. When rerere is enabled, Git will keep a set of pre- and post-images from successful merges, and if it notices that there's a conflict that looks exactly like one you've already fixed, it'll just use the fix from last time, without bothering you with it. This feature comes in two parts: a configuration setting and a command. @@ -422,14 +423,14 @@ Now, whenever you do a merge that resolves conflicts, the resolution will be rec If you need to, you can interact with the rerere cache using the `git rerere` command. When it's invoked alone, Git checks its database of resolutions and tries to find a match with any current merge conflicts and resolve them (although this is done automatically if `rerere.enabled` is set to `true`). There are also subcommands to see what will be recorded, to erase specific resolution from the cache, and to clear the entire cache. -We will cover rerere in more detail in <<_rerere>>. +We will cover rerere in more detail in <>. [[_tagging_releases]] ==== Tagging Your Releases (((tags)))(((tags, signing))) When you've decided to cut a release, you'll probably want to assign a tag so you can re-create that release at any point going forward. -You can create a new tag as discussed in <<_git_basics_chapter>>. +You can create a new tag as discussed in <>. If you decide to sign the tag as the maintainer, the tagging may look something like this: [source,console] @@ -485,7 +486,7 @@ Also, if you include instructions in the tag message, running `git show ` w (((build numbers)))(((git commands, describe))) Because Git doesn't have monotonically increasing numbers like 'v123' or the equivalent to go with each commit, if you want to have a human-readable name to go with a commit, you can run `git describe` on that commit. -Git gives you the name of the nearest tag with the number of commits on top of that tag and a partial SHA-1 value of the commit you're describing: +In response, Git generates a string consisting of the name of the most recent tag earlier than that commit, followed by the number of commits since that tag, followed finally by a partial SHA-1 value of the commit being described (prefixed with the letter "g" meaning Git): [source,console] ---- @@ -495,10 +496,10 @@ v1.6.2-rc1-20-g8c5b85c This way, you can export a snapshot or build and name it something understandable to people. In fact, if you build Git from source code cloned from the Git repository, `git --version` gives you something that looks like this. -If you're describing a commit that you have directly tagged, it gives you the tag name. +If you're describing a commit that you have directly tagged, it gives you simply the tag name. -The `git describe` command favors annotated tags (tags created with the `-a` or `-s` flag), so release tags should be created this way if you're using `git describe`, to ensure the commit is named properly when described. -You can also use this string as the target of a checkout or show command, although it relies on the abbreviated SHA-1 value at the end, so it may not be valid forever. +By default, the `git describe` command requires annotated tags (tags created with the `-a` or `-s` flag); if you want to take advantage of lightweight (non-annotated) tags as well, add the `--tags` option to the command. +You can also use this string as the target of a `git checkout` or `git show` command, although it relies on the abbreviated SHA-1 value at the end, so it may not be valid forever. For instance, the Linux kernel recently jumped from 8 to 10 characters to ensure SHA-1 object uniqueness, so older `git describe` output names were invalidated. [[_preparing_release]] @@ -516,7 +517,7 @@ $ ls *.tar.gz v1.6.2-rc1-20-g8c5b85c.tar.gz ---- -If someone opens that tarball, they get the latest snapshot of your project under a project directory. +If someone opens that tarball, they get the latest snapshot of your project under a `project` directory. You can also create a zip archive in much the same way, but by passing the `--format=zip` option to `git archive`: [source,console] @@ -537,7 +538,7 @@ It summarizes all the commits in the range you give it; for example, the followi [source,console] ---- $ git shortlog --no-merges master --not v1.0.1 -Chris Wanstrath (8): +Chris Wanstrath (6): Add support for annotated tags to Grit::Tag Add packed-refs annotated tag support. Add Grit::Commit#to_patch diff --git a/book/06-github/sections/1-setting-up-account.asc b/book/06-github/sections/1-setting-up-account.asc index 922efc5d5..475c7edf9 100644 --- a/book/06-github/sections/1-setting-up-account.asc +++ b/book/06-github/sections/1-setting-up-account.asc @@ -9,12 +9,15 @@ image::images/signup.png[The GitHub sign-up form.] The next thing you'll see is the pricing page for upgraded plans, but it's safe to ignore this for now. GitHub will send you an email to verify the address you provided. -Go ahead and do this, it's pretty important (as we'll see later). +Go ahead and do this; it's pretty important (as we'll see later). [NOTE] ==== -GitHub provides all of its functionality with free accounts, with the limitation that all of your projects are fully public (everyone has read access). -GitHub's paid plans include a set number of private projects, but we won't be covering those in this book. +GitHub provides almost all of its functionality with free accounts, except some advanced features. +Additionally, private repositories are limited to 3 collaborators. + +GitHub's paid plans include advanced tools and features as well as increased limits for free services, but we won't be covering those in this book. +To get more information about available plans and their comparison, visit https://github.com/pricing[]. ==== Clicking the Octocat logo at the top-left of the screen will take you to your dashboard page. @@ -27,7 +30,7 @@ As of right now, you're fully able to connect with Git repositories using the `h However, to simply clone public projects, you don't even need to sign up - the account we just created comes into play when we fork projects and push to our forks a bit later. If you'd like to use SSH remotes, you'll need to configure a public key. -(If you don't already have one, see <<_generate_ssh_key>>.) +(If you don't already have one, see <>.) Open up your account settings using the link at the top-right of the window: .The ``Account settings'' link. diff --git a/book/06-github/sections/2-contributing.asc b/book/06-github/sections/2-contributing.asc index 722be2313..e5bbb9d79 100644 --- a/book/06-github/sections/2-contributing.asc +++ b/book/06-github/sections/2-contributing.asc @@ -5,7 +5,7 @@ Now that our account is set up, let's walk through some details that could be us ==== Forking Projects (((forking))) -If you want to contribute to an existing project to which you don’t have push access, you can ``fork'' the project. +If you want to contribute to an existing project to which you don't have push access, you can ``fork'' the project. When you ``fork'' a project, GitHub will make a copy of the project that is entirely yours; it lives in your namespace, and you can push to it. [NOTE] @@ -14,7 +14,7 @@ Historically, the term ``fork'' has been somewhat negative in context, meaning t In GitHub, a ``fork'' is simply the same project in your own namespace, allowing you to make changes to a project publicly as a way to contribute in a more open manner. ==== -This way, projects don’t have to worry about adding users as collaborators to give them push access. +This way, projects don't have to worry about adding users as collaborators to give them push access. People can fork a project, push to it, and contribute their changes back to the original repository by creating what's called a Pull Request, which we'll cover next. This opens up a discussion thread with code review, and the owner and the contributor can then communicate about the change until the owner is happy with it, at which point the owner can merge it in. @@ -26,13 +26,13 @@ image::images/forkbutton.png[The ``Fork'' button.] After a few seconds, you'll be taken to your new project page, with your own writeable copy of the code. -[[_github_flow]] +[[ch06-github_flow]] ==== The GitHub Flow (((GitHub, Flow))) GitHub is designed around a particular collaboration workflow, centered on Pull Requests. This flow works whether you're collaborating with a tightly-knit team in a single shared repository, or a globally-distributed company or network of strangers contributing to a project through dozens of forks. -It is centered on the <<_topic_branch>> workflow covered in <<_git_branching>>. +It is centered on the <> workflow covered in <>. Here's how it generally works: @@ -43,8 +43,9 @@ Here's how it generally works: 5. Open a Pull Request on GitHub. 6. Discuss, and optionally continue committing. 7. The project owner merges or closes the Pull Request. +8. Sync the updated master back to your fork. -This is basically the Integration Manager workflow covered in <<_integration_manager>>, but instead of using email to communicate and review changes, teams use GitHub's web based tools. +This is basically the Integration Manager workflow covered in <>, but instead of using email to communicate and review changes, teams use GitHub's web based tools. Let's walk through an example of proposing a change to an open source project hosted on GitHub using this flow. @@ -55,7 +56,8 @@ Tony is looking for code to run on his Arduino programmable microcontroller and .The project we want to contribute to. image::images/blink-01-start.png[The project we want to contribute to.] -The only problem is that the blinking rate is too fast, we think it's much nicer to wait 3 seconds instead of 1 in between each state change. +The only problem is that the blinking rate is too fast. +We think it's much nicer to wait 3 seconds instead of 1 in between each state change. So let's improve the program and submit it back to the project as a proposed change. First, we click the 'Fork' button as mentioned earlier to get our own copy of the project. @@ -89,8 +91,8 @@ void loop() { [-delay(1000);-]{+delay(3000);+} // wait for a second } -$ git commit -a -m 'three seconds is better' <5> -[slow-blink 5ca509d] three seconds is better +$ git commit -a -m 'Change delay to 3 seconds' <5> +[slow-blink 5ca509d] Change delay to 3 seconds 1 file changed, 2 insertions(+), 2 deletions(-) $ git push origin slow-blink <6> @@ -132,25 +134,31 @@ When you hit the 'Create pull request' button on this screen, the owner of the p [NOTE] ==== -Though Pull Requests are used commonly for public projects like this when the contributor has a complete change ready to be made, it's also often used in internal projects _at the beginning_ of the development cycle. Since you can keep pushing to the topic branch even *after* the Pull Request is opened, it's often opened early and used as a way to iterate on work as a team within a context, rather than opened at the very end of the process. +Though Pull Requests are used commonly for public projects like this when the contributor has a complete change ready to be made, it's also often used in internal projects _at the beginning_ of the development cycle. +Since you can keep pushing to the topic branch even *after* the Pull Request is opened, it's often opened early and used as a way to iterate on work as a team within a context, rather than opened at the very end of the process. ==== ===== Iterating on a Pull Request -At this point, the project owner can look at the suggested change and merge it, reject it or comment on it. Let's say that he likes the idea, but would prefer a slightly longer time for the light to be off than on. +At this point, the project owner can look at the suggested change and merge it, reject it or comment on it. +Let's say that he likes the idea, but would prefer a slightly longer time for the light to be off than on. -Where this conversation may take place over email in the workflows presented in <<_distributed_git>>, on GitHub this happens online. The project owner can review the unified diff and leave a comment by clicking on any of the lines. +Where this conversation may take place over email in the workflows presented in <>, on GitHub this happens online. +The project owner can review the unified diff and leave a comment by clicking on any of the lines. .Comment on a specific line of code in a Pull Request image::images/blink-04-pr-comment.png[PR line comment] -Once the maintainer makes this comment, the person who opened the Pull Request (and indeed, anyone else watching the repository) will get a notification. We'll go over customizing this later, but if he had email notifications turned on, Tony would get an email like this: +Once the maintainer makes this comment, the person who opened the Pull Request (and indeed, anyone else watching the repository) will get a notification. +We'll go over customizing this later, but if he had email notifications turned on, Tony would get an email like this: [[_email_notification]] .Comments sent as email notifications image::images/blink-04-email.png[Email notification] -Anyone can also leave general comments on the Pull Request. In <<_pr_discussion>> we can see an example of the project owner both commenting on a line of code and then leaving a general comment in the discussion section. You can see that the code comments are brought into the conversation as well. +Anyone can also leave general comments on the Pull Request. +In <<_pr_discussion>> we can see an example of the project owner both commenting on a line of code and then leaving a general comment in the discussion section. +You can see that the code comments are brought into the conversation as well. [[_pr_discussion]] .Pull Request discussion page @@ -167,18 +175,26 @@ Adding commits to an existing Pull Request doesn't trigger a notification, so on .Pull Request final image::images/blink-06-final.png[PR final] -An interesting thing to notice is that if you click on the ``Files Changed'' tab on this Pull Request, you'll get the ``unified'' diff -- that is, the total aggregate difference that would be introduced to your main branch if this topic branch was merged in. In `git diff` terms, it basically automatically shows you `git diff master...` for the branch this Pull Request is based on. See <<_what_is_introduced>> for more about this type of diff. +An interesting thing to notice is that if you click on the ``Files Changed'' tab on this Pull Request, you'll get the ``unified'' diff -- that is, the total aggregate difference that would be introduced to your main branch if this topic branch was merged in. +In `git diff` terms, it basically automatically shows you `git diff master...` for the branch this Pull Request is based on. +See <> for more about this type of diff. -The other thing you'll notice is that GitHub checks to see if the Pull Request merges cleanly and provides a button to do the merge for you on the server. This button only shows up if you have write access to the repository and a trivial merge is possible. If you click it GitHub will perform a ``non-fast-forward'' merge, meaning that even if the merge *could* be a fast-forward, it will still create a merge commit. +The other thing you'll notice is that GitHub checks to see if the Pull Request merges cleanly and provides a button to do the merge for you on the server. +This button only shows up if you have write access to the repository and a trivial merge is possible. +If you click it GitHub will perform a ``non-fast-forward'' merge, meaning that even if the merge *could* be a fast-forward, it will still create a merge commit. -If you would prefer, you can simply pull the branch down and merge it locally. If you merge this branch into the `master` branch and push it to GitHub, the Pull Request will automatically be closed. +If you would prefer, you can simply pull the branch down and merge it locally. +If you merge this branch into the `master` branch and push it to GitHub, the Pull Request will automatically be closed. -This is the basic workflow that most GitHub projects use. Topic branches are created, Pull Requests are opened on them, a discussion ensues, possibly more work is done on the branch and eventually the request is either closed or merged. +This is the basic workflow that most GitHub projects use. +Topic branches are created, Pull Requests are opened on them, a discussion ensues, possibly more work is done on the branch and eventually the request is either closed or merged. [NOTE] .Not Only Forks ==== -It's important to note that you can also open a Pull Request between two branches in the same repository. If you're working on a feature with someone and you both have write access to the project, you can push a topic branch to the repository and open a Pull Request on it to the `master` branch of that same project to initiate the code review and discussion process. No forking necessary. +It's important to note that you can also open a Pull Request between two branches in the same repository. +If you're working on a feature with someone and you both have write access to the project, you can push a topic branch to the repository and open a Pull Request on it to the `master` branch of that same project to initiate the code review and discussion process. +No forking necessary. ==== ==== Advanced Pull Requests @@ -187,15 +203,22 @@ Now that we've covered the basics of contributing to a project on GitHub, let's ===== Pull Requests as Patches -It's important to understand that many projects don't really think of Pull Requests as queues of perfect patches that should apply cleanly in order, as most mailing list-based projects think of patch series contributions. Most GitHub projects think about Pull Request branches as iterative conversations around a proposed change, culminating in a unified diff that is applied by merging. +It's important to understand that many projects don't really think of Pull Requests as queues of perfect patches that should apply cleanly in order, as most mailing list-based projects think of patch series contributions. +Most GitHub projects think about Pull Request branches as iterative conversations around a proposed change, culminating in a unified diff that is applied by merging. -This is an important distinction, because generally the change is suggested before the code is thought to be perfect, which is far more rare with mailing list based patch series contributions. This enables an earlier conversation with the maintainers so that arriving at the proper solution is more of a community effort. When code is proposed with a Pull Request and the maintainers or community suggest a change, the patch series is generally not re-rolled, but instead the difference is pushed as a new commit to the branch, moving the conversation forward with the context of the previous work intact. +This is an important distinction, because generally the change is suggested before the code is thought to be perfect, which is far more rare with mailing list based patch series contributions. +This enables an earlier conversation with the maintainers so that arriving at the proper solution is more of a community effort. +When code is proposed with a Pull Request and the maintainers or community suggest a change, the patch series is generally not re-rolled, but instead the difference is pushed as a new commit to the branch, moving the conversation forward with the context of the previous work intact. -For instance, if you go back and look again at <<_pr_final>>, you'll notice that the contributor did not rebase his commit and send another Pull Request. Instead they added new commits and pushed them to the existing branch. This way if you go back and look at this Pull Request in the future, you can easily find all of the context of why decisions were made. Pushing the ``Merge'' button on the site purposefully creates a merge commit that references the Pull Request so that it's easy to go back and research the original conversation if necessary. +For instance, if you go back and look again at <<_pr_final>>, you'll notice that the contributor did not rebase his commit and send another Pull Request. +Instead they added new commits and pushed them to the existing branch. +This way if you go back and look at this Pull Request in the future, you can easily find all of the context of why decisions were made. +Pushing the ``Merge'' button on the site purposefully creates a merge commit that references the Pull Request so that it's easy to go back and research the original conversation if necessary. ===== Keeping up with Upstream -If your Pull Request becomes out of date or otherwise doesn't merge cleanly, you will want to fix it so the maintainer can easily merge it. GitHub will test this for you and let you know at the bottom of every Pull Request if the merge is trivial or not. +If your Pull Request becomes out of date or otherwise doesn't merge cleanly, you will want to fix it so the maintainer can easily merge it. +GitHub will test this for you and let you know at the bottom of every Pull Request if the merge is trivial or not. [[_pr_fail]] .Pull Request does not merge cleanly @@ -203,13 +226,16 @@ image::images/pr-01-fail.png[PR merge failure] If you see something like <<_pr_fail>>, you'll want to fix your branch so that it turns green and the maintainer doesn't have to do extra work. -You have two main options in order to do this. You can either rebase your branch on top of whatever the target branch is (normally the `master` branch of the repository you forked), or you can merge the target branch into your branch. +You have two main options in order to do this. +You can either rebase your branch on top of whatever the target branch is (normally the `master` branch of the repository you forked), or you can merge the target branch into your branch. -Most developers on GitHub will choose to do the latter, for the same reasons we just went over in the previous section. What matters is the history and the final merge, so rebasing isn't getting you much other than a slightly cleaner history and in return is *far* more difficult and error prone. +Most developers on GitHub will choose to do the latter, for the same reasons we just went over in the previous section. +What matters is the history and the final merge, so rebasing isn't getting you much other than a slightly cleaner history and in return is *far* more difficult and error prone. If you want to merge in the target branch to make your Pull Request mergeable, you would add the original repository as a new remote, fetch from it, merge the main branch of that repository into your topic branch, fix any issues and finally push it back up to the same branch you opened the Pull Request on. -For example, let's say that in the ``tonychacon'' example we were using before, the original author made a change that would create a conflict in the Pull Request. Let's go through those steps. +For example, let's say that in the ``tonychacon'' example we were using before, the original author made a change that would create a conflict in the Pull Request. +Let's go through those steps. [source,console] ---- @@ -256,17 +282,28 @@ Once you do that, the Pull Request will be automatically updated and re-checked .Pull Request now merges cleanly image::images/pr-02-merge-fix.png[PR fixed] -One of the great things about Git is that you can do that continuously. If you have a very long-running project, you can easily merge from the target branch over and over again and only have to deal with conflicts that have arisen since the last time that you merged, making the process very manageable. +One of the great things about Git is that you can do that continuously. +If you have a very long-running project, you can easily merge from the target branch over and over again and only have to deal with conflicts that have arisen since the last time that you merged, making the process very manageable. -If you absolutely wish to rebase the branch to clean it up, you can certainly do so, but it is highly encouraged to not force push over the branch that the Pull Request is already opened on. If other people have pulled it down and done more work on it, you run into all of the issues outlined in <<_rebase_peril>>. Instead, push the rebased branch to a new branch on GitHub and open a brand new Pull Request referencing the old one, then close the original. +If you absolutely wish to rebase the branch to clean it up, you can certainly do so, but it is highly encouraged to not force push over the branch that the Pull Request is already opened on. +If other people have pulled it down and done more work on it, you run into all of the issues outlined in <>. +Instead, push the rebased branch to a new branch on GitHub and open a brand new Pull Request referencing the old one, then close the original. ===== References -Your next question may be ``How do I reference the old Pull Request?''. It turns out there are many, many ways to reference other things almost anywhere you can write in GitHub. +Your next question may be ``How do I reference the old Pull Request?''. +It turns out there are many, many ways to reference other things almost anywhere you can write in GitHub. -Let's start with how to cross-reference another Pull Request or an Issue. All Pull Requests and Issues are assigned numbers and they are unique within the project. For example, you can't have Pull Request #3 _and_ Issue #3. If you want to reference any Pull Request or Issue from any other one, you can simply put `#` in any comment or description. You can also be more specific if the Issue or Pull request lives somewhere else; write `username#` if you're referring to an Issue or Pull Request in a fork of the repository you're in, or `username/repo#` to reference something in another repository. +Let's start with how to cross-reference another Pull Request or an Issue. +All Pull Requests and Issues are assigned numbers and they are unique within the project. +For example, you can't have Pull Request #3 _and_ Issue #3. +If you want to reference any Pull Request or Issue from any other one, you can simply put `#` in any comment or description. +You can also be more specific if the Issue or Pull request lives somewhere else; write `username#` if you're referring to an Issue or Pull Request in a fork of the repository you're in, or `username/repo#` to reference something in another repository. -Let's look at an example. Say we rebased the branch in the previous example, created a new pull request for it, and now we want to reference the old pull request from the new one. We also want to reference an issue in the fork of the repository and an issue in a completely different project. We can fill out the description just like <<_pr_references>>. +Let's look at an example. +Say we rebased the branch in the previous example, created a new pull request for it, and now we want to reference the old pull request from the new one. +We also want to reference an issue in the fork of the repository and an issue in a completely different project. +We can fill out the description just like <<_pr_references>>. [[_pr_references]] .Cross references in a Pull Request. @@ -280,17 +317,23 @@ image::images/mentions-02-render.png[PR references rendered] Notice that the full GitHub URL we put in there was shortened to just the information needed. -Now if Tony goes back and closes out the original Pull Request, we can see that by mentioning it in the new one, GitHub has automatically created a trackback event in the Pull Request timeline. This means that anyone who visits this Pull Request and sees that it is closed can easily link back to the one that superseded it. The link will look something like <<_pr_closed>>. +Now if Tony goes back and closes out the original Pull Request, we can see that by mentioning it in the new one, GitHub has automatically created a trackback event in the Pull Request timeline. +This means that anyone who visits this Pull Request and sees that it is closed can easily link back to the one that superseded it. +The link will look something like <<_pr_closed>>. [[_pr_closed]] .Link back to the new Pull Request in the closed Pull Request timeline. image::images/mentions-03-closed.png[PR closed] -In addition to issue numbers, you can also reference a specific commit by SHA-1. You have to specify a full 40 character SHA-1, but if GitHub sees that in a comment, it will link directly to the commit. Again, you can reference commits in forks or other repositories in the same way you did with issues. +In addition to issue numbers, you can also reference a specific commit by SHA-1. +You have to specify a full 40 character SHA-1, but if GitHub sees that in a comment, it will link directly to the commit. +Again, you can reference commits in forks or other repositories in the same way you did with issues. ==== GitHub Flavored Markdown -Linking to other Issues is just the beginning of interesting things you can do with almost any text box on GitHub. In Issue and Pull Request descriptions, comments, code comments and more, you can use what is called ``GitHub Flavored Markdown''. Markdown is like writing in plain text but which is rendered richly. +Linking to other Issues is just the beginning of interesting things you can do with almost any text box on GitHub. +In Issue and Pull Request descriptions, comments, code comments and more, you can use what is called ``GitHub Flavored Markdown''. +Markdown is like writing in plain text but which is rendered richly. See <<_example_markdown>> for an example of how comments or text can be written and then rendered using Markdown. @@ -298,11 +341,14 @@ See <<_example_markdown>> for an example of how comments or text can be written .An example of GitHub Flavored Markdown as written and as rendered. image::images/markdown-01-example.png[Example Markdown] -The GitHub flavor of Markdown adds more things you can do beyond the basic Markdown syntax. These can all be really useful when creating useful Pull Request or Issue comments or descriptions. +The GitHub flavor of Markdown adds more things you can do beyond the basic Markdown syntax. +These can all be really useful when creating useful Pull Request or Issue comments or descriptions. ===== Task Lists -The first really useful GitHub specific Markdown feature, especially for use in Pull Requests, is the Task List. A task list is a list of checkboxes of things you want to get done. Putting them into an Issue or Pull Request normally indicates things that you want to get done before you consider the item complete. +The first really useful GitHub specific Markdown feature, especially for use in Pull Requests, is the Task List. +A task list is a list of checkboxes of things you want to get done. +Putting them into an Issue or Pull Request normally indicates things that you want to get done before you consider the item complete. You can create a task list like this: @@ -313,15 +359,19 @@ You can create a task list like this: - [ ] Document the code ---- -If we include this in the description of our Pull Request or Issue, we'll see it rendered like <<_task_lists>> +If we include this in the description of our Pull Request or Issue, we'll see it rendered like <<_eg_task_lists>> -[[_task_lists]] +[[_eg_task_lists]] .Task lists rendered in a Markdown comment. image::images/markdown-02-tasks.png[Example Task List] -This is often used in Pull Requests to indicate what all you would like to get done on the branch before the Pull Request will be ready to merge. The really cool part is that you can simply click the checkboxes to update the comment -- you don't have to edit the Markdown directly to check tasks off. +This is often used in Pull Requests to indicate what all you would like to get done on the branch before the Pull Request will be ready to merge. +The really cool part is that you can simply click the checkboxes to update the comment -- you don't have to edit the Markdown directly to check tasks off. -What's more, GitHub will look for task lists in your Issues and Pull Requests and show them as metadata on the pages that list them out. For example, if you have a Pull Request with tasks and you look at the overview page of all Pull Requests, you can see how far done it is. This helps people break down Pull Requests into subtasks and helps other people track the progress of the branch. You can see an example of this in <<_task_list_progress>>. +What's more, GitHub will look for task lists in your Issues and Pull Requests and show them as metadata on the pages that list them out. +For example, if you have a Pull Request with tasks and you look at the overview page of all Pull Requests, you can see how far done it is. +This helps people break down Pull Requests into subtasks and helps other people track the progress of the branch. +You can see an example of this in <<_task_list_progress>>. [[_task_list_progress]] .Task list summary in the Pull Request list. @@ -331,7 +381,9 @@ These are incredibly useful when you open a Pull Request early and use it to tra ===== Code Snippets -You can also add code snippets to comments. This is especially useful if you want to present something that you _could_ try to do before actually implementing it as a commit on your branch. This is also often used to add example code of what is not working or what this Pull Request could implement. +You can also add code snippets to comments. +This is especially useful if you want to present something that you _could_ try to do before actually implementing it as a commit on your branch. +This is also often used to add example code of what is not working or what this Pull Request could implement. To add a snippet of code you have to ``fence'' it in backticks. @@ -345,7 +397,8 @@ for(int i=0 ; i < 5 ; i++) ``` ---- -If you add a language name like we did there with 'java', GitHub will also try to syntax highlight the snippet. In the case of the above example, it would end up rendering like <<_md_code>>. +If you add a language name like we did there with 'java', GitHub will also try to syntax highlight the snippet. +In the case of the above example, it would end up rendering like <<_md_code>>. [[_md_code]] .Rendered fenced code example. @@ -353,7 +406,9 @@ image::images/markdown-04-fenced-code.png[Rendered fenced code] ===== Quoting -If you're responding to a small part of a long comment, you can selectively quote out of the other comment by preceding the lines with the `>` character. In fact, this is so common and so useful that there is a keyboard shortcut for it. If you highlight text in a comment that you want to directly reply to and hit the `r` key, it will quote that text in the comment box for you. +If you're responding to a small part of a long comment, you can selectively quote out of the other comment by preceding the lines with the `>` character. +In fact, this is so common and so useful that there is a keyboard shortcut for it. +If you highlight text in a comment that you want to directly reply to and hit the `r` key, it will quote that text in the comment box for you. The quotes look something like this: @@ -373,13 +428,17 @@ image::images/markdown-05-quote.png[Rendered quoting] ===== Emoji -Finally, you can also use emoji in your comments. This is actually used quite extensively in comments you see on many GitHub Issues and Pull Requests. There is even an emoji helper in GitHub. If you are typing a comment and you start with a `:` character, an autocompleter will help you find what you're looking for. +Finally, you can also use emoji in your comments. +This is actually used quite extensively in comments you see on many GitHub Issues and Pull Requests. +There is even an emoji helper in GitHub. +If you are typing a comment and you start with a `:` character, an autocompleter will help you find what you're looking for. [[_md_emoji_auto]] .Emoji autocompleter in action. image::images/markdown-06-emoji-complete.png[Emoji autocompleter] -Emojis take the form of `::` anywhere in the comment. For instance, you could write something like this: +Emojis take the form of `::` anywhere in the comment. +For instance, you could write something like this: [source,text] ---- @@ -403,17 +462,80 @@ Not that this is incredibly useful, but it does add an element of fun and emotio [NOTE] ==== -There are actually quite a number of web services that make use of emoji characters these days. A great cheat sheet to reference to find emoji that expresses what you want to say can be found at: +There are actually quite a number of web services that make use of emoji characters these days. +A great cheat sheet to reference to find emoji that expresses what you want to say can be found at: -http://www.emoji-cheat-sheet.com +https://www.webfx.com/tools/emoji-cheat-sheet/ ==== ===== Images -This isn't technically GitHub Flavored Markdown, but it is incredibly useful. In addition to adding Markdown image links to comments, which can be difficult to find and embed URLs for, GitHub allows you to drag and drop images into text areas to embed them. +This isn't technically GitHub Flavored Markdown, but it is incredibly useful. +In addition to adding Markdown image links to comments, which can be difficult to find and embed URLs for, GitHub allows you to drag and drop images into text areas to embed them. [[_md_drag]] .Drag and drop images to upload them and auto-embed them. image::images/markdown-08-drag-drop.png[Drag and drop images] -If you look at <<_md_drag>>, you can see a small ``Parsed as Markdown'' hint above the text area. Clicking on that will give you a full cheat sheet of everything you can do with Markdown on GitHub. +If you look at <<_md_drag>>, you can see a small ``Parsed as Markdown'' hint above the text area. +Clicking on that will give you a full cheat sheet of everything you can do with Markdown on GitHub. + +[[_fetch_and_push_on_different_repositories]] +==== Keep your GitHub public repository up-to-date + +Once you've forked a GitHub repository, your repository (your "fork") exists independently from the original. +In particular, when the original repository has new commits, GitHub informs you by a message like: + +[source,text] +---- +This branch is 5 commits behind progit:master. +---- + +But your GitHub repository will never be automatically updated by GitHub; this is something that you must do yourself. +Fortunately, this is very easy to do. + +One possibility to do this requires no configuration. +For example, if you forked from `https://github.com/progit/progit2.git`, you can keep your `master` branch up-to-date like this: + +[source,console] +---- +$ git checkout master <1> +$ git pull https://github.com/progit/progit2.git <2> +$ git push origin master <3> +---- + +<1> If you were on another branch, return to `master`. +<2> Fetch changes from `https://github.com/progit/progit2.git` and merge them into `master`. +<3> Push your `master` branch to `origin`. + +This works, but it is a little tedious having to spell out the fetch URL every time. +You can automate this work with a bit of configuration: + +[source,console] +---- +$ git remote add progit https://github.com/progit/progit2.git <1> +$ git branch --set-upstream-to=progit/master master <2> +$ git config --local remote.pushDefault origin <3> +---- + +<1> Add the source repository and give it a name. + Here, I have chosen to call it `progit`. +<2> Set your `master` branch to fetch from the `progit` remote. +<3> Define the default push repository to `origin`. + +Once this is done, the workflow becomes much simpler: + +[source,console] +---- +$ git checkout master <1> +$ git pull <2> +$ git push <3> +---- + +<1> If you were on another branch, return to `master`. +<2> Fetch changes from `progit` and merge changes into `master`. +<3> Push your `master` branch to `origin`. + +This approach can be useful, but it's not without downsides. +Git will happily do this work for you silently, but it won't warn you if you make a commit to `master`, pull from `progit`, then push to `origin` -- all of those operations are valid with this setup. +So you'll have to take care never to commit directly to `master`, since that branch effectively belongs to the upstream repository. diff --git a/book/06-github/sections/3-maintaining.asc b/book/06-github/sections/3-maintaining.asc index 5612f874a..f174e15e9 100644 --- a/book/06-github/sections/3-maintaining.asc +++ b/book/06-github/sections/3-maintaining.asc @@ -24,7 +24,7 @@ All you really have to do here is provide a project name; the rest of the fields For now, just click the ``Create Repository'' button, and boom – you have a new repository on GitHub, named `/`. Since you have no code there yet, GitHub will show you instructions for how to create a brand-new Git repository, or connect an existing Git project. -We won't belabor this here; if you need a refresher, check out <<_git_basics_chapter>>. +We won't belabor this here; if you need a refresher, check out <>. Now that your project is hosted on GitHub, you can give the URL to anyone you want to share your project with. Every project on GitHub is accessible over HTTPS as `https://github.com//`, and over SSH as `git@github.com:/`. @@ -81,7 +81,7 @@ It gives you a link to the Pull Request on GitHub. It also gives you a few URLs that you can use from the command line. If you notice the line that says `git pull patch-1`, this is a simple way to merge in a remote branch without having to add a remote. -We went over this quickly in <<_checking_out_remotes>>. +We went over this quickly in <>. If you wish, you can create and switch to a topic branch and then run this command to merge in the Pull Request changes. The other interesting URLs are the `.diff` and `.patch` URLs, which as you may guess, provide unified diff and patch versions of the Pull Request. @@ -89,12 +89,12 @@ You could technically merge in the Pull Request work with something like this: [source,console] ---- -$ curl http://github.com/tonychacon/fade/pull/1.patch | git am +$ curl https://github.com/tonychacon/fade/pull/1.patch | git am ---- ===== Collaborating on the Pull Request -As we covered in <<_github_flow>>, you can now have a conversation with the person who opened the Pull Request. +As we covered in <>, you can now have a conversation with the person who opened the Pull Request. You can comment on specific lines of code, comment on whole commits or comment on the entire Pull Request itself, using GitHub Flavored Markdown everywhere. Every time someone else comments on the Pull Request you will continue to get email notifications so you know there is activity happening. @@ -120,12 +120,12 @@ If you decide you don't want to merge it, you can also just close the Pull Reque ===== Pull Request Refs If you're dealing with a *lot* of Pull Requests and don't want to add a bunch of remotes or do one time pulls every time, there is a neat trick that GitHub allows you to do. -This is a bit of an advanced trick and we'll go over the details of this a bit more in <<_refspec>>, but it can be pretty useful. +This is a bit of an advanced trick and we'll go over the details of this a bit more in <>, but it can be pretty useful. GitHub actually advertises the Pull Request branches for a repository as sort of pseudo-branches on the server. By default you don't get them when you clone, but they are there in an obscured way and you can access them pretty easily. -To demonstrate this, we're going to use a low-level command (often referred to as a ``plumbing'' command, which we'll read about more in <<_plumbing_porcelain>>) called `ls-remote`. +To demonstrate this, we're going to use a low-level command (often referred to as a ``plumbing'' command, which we'll read about more in <>) called `ls-remote`. This command is generally not used in day-to-day Git operations but it's useful to show us what references are present on the server. If we run this command against the ``blink'' repository we were using earlier, we will get a list of all the branches and tags and other references in the repository. diff --git a/book/06-github/sections/4-managing-organization.asc b/book/06-github/sections/4-managing-organization.asc index ea2119081..f3137e5dc 100644 --- a/book/06-github/sections/4-managing-organization.asc +++ b/book/06-github/sections/4-managing-organization.asc @@ -1,4 +1,4 @@ -[[_github_orgs]] +[[ch06-github_orgs]] === Managing an organization (((GitHub, organizations))) @@ -65,7 +65,7 @@ Special-interest teams like `ux`, `css`, or `refactoring` are useful for certain Organizations also give owners access to all the information about what went on under the organization. You can go to the 'Audit Log' tab and see what events have happened at an organization level, who did them and where in the world they were done. -[[_audit_log]] +[[_the_audit_log]] .The Audit log. image::images/orgs-03-audit.png[] diff --git a/book/06-github/sections/5-scripting.asc b/book/06-github/sections/5-scripting.asc index 6bfb16e77..b85917d73 100644 --- a/book/06-github/sections/5-scripting.asc +++ b/book/06-github/sections/5-scripting.asc @@ -159,7 +159,7 @@ $ curl https://api.github.com/gitignore/templates/Java *.war *.ear -# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml +# virtual machine crash logs, see https://www.java.com/en/download/help/error_hotspot.xml hs_err_pid* " } @@ -296,7 +296,7 @@ This is really useful if you're using this API for test results so you don't acc Though we've been doing nearly everything through `curl` and simple HTTP requests in these examples, several open-source libraries exist that make this API available in a more idiomatic way. At the time of this writing, the supported languages include Go, Objective-C, Ruby, and .NET. -Check out http://github.com/octokit[] for more information on these, as they handle much of the HTTP for you. +Check out https://github.com/octokit[] for more information on these, as they handle much of the HTTP for you. Hopefully these tools can help you customize and modify GitHub to work better for your specific workflows. For complete documentation on the entire API as well as guides for common tasks, check out https://developer.github.com[]. diff --git a/book/07-git-tools/1-git-tools.asc b/book/07-git-tools/1-git-tools.asc deleted file mode 100644 index 073eae5fd..000000000 --- a/book/07-git-tools/1-git-tools.asc +++ /dev/null @@ -1,42 +0,0 @@ -[[_git_tools]] -== Git Tools - -By now, you’ve learned most of the day-to-day commands and workflows that you need to manage or maintain a Git repository for your source code control. -You’ve accomplished the basic tasks of tracking and committing files, and you’ve harnessed the power of the staging area and lightweight topic branching and merging. - -Now you’ll explore a number of very powerful things that Git can do that you may not necessarily use on a day-to-day basis but that you may need at some point. - -include::sections/revision-selection.asc[] - -include::sections/interactive-staging.asc[] - -include::sections/stashing-cleaning.asc[] - -include::sections/signing.asc[] - -include::sections/searching.asc[] - -include::sections/rewriting-history.asc[] - -include::sections/reset.asc[] - -include::sections/advanced-merging.asc[] - -include::sections/rerere.asc[] - -include::sections/debugging.asc[] - -include::sections/submodules.asc[] - -include::sections/bundling.asc[] - -include::sections/replace.asc[] - -include::sections/credentials.asc[] - -=== Summary - -You’ve seen a number of advanced tools that allow you to manipulate your commits and staging area more precisely. -When you notice issues, you should be able to easily figure out what commit introduced them, when, and by whom. -If you want to use subprojects in your project, you’ve learned how to accommodate those needs. -At this point, you should be able to do most of the things in Git that you’ll need on the command line day to day and feel comfortable doing so. diff --git a/book/07-git-tools/sections/advanced-merging.asc b/book/07-git-tools/sections/advanced-merging.asc index 1c3767179..1f1191c47 100644 --- a/book/07-git-tools/sections/advanced-merging.asc +++ b/book/07-git-tools/sections/advanced-merging.asc @@ -14,12 +14,12 @@ We'll also cover some of the different, non-standard types of merges you can do, ==== Merge Conflicts -While we covered some basics on resolving merge conflicts in <<_basic_merge_conflicts>>, for more complex conflicts, Git provides a few tools to help you figure out what's going on and how to better deal with the conflict. +While we covered some basics on resolving merge conflicts in <>, for more complex conflicts, Git provides a few tools to help you figure out what's going on and how to better deal with the conflict. First of all, if at all possible, try to make sure your working directory is clean before doing a merge that may have conflicts. If you have work in progress, either commit it to a temporary branch or stash it. This makes it so that you can undo *anything* you try here. -If you have unsaved changes in your working directory when you try a merge, some of these tips may help you lose that work. +If you have unsaved changes in your working directory when you try a merge, some of these tips may help you preserve that work. Let's walk through a very simple example. We have a super simple Ruby file that prints 'hello world'. @@ -45,8 +45,8 @@ Switched to a new branch 'whitespace' $ unix2dos hello.rb unix2dos: converting file hello.rb to DOS format ... -$ git commit -am 'converted hello.rb to DOS' -[whitespace 3270f76] converted hello.rb to DOS +$ git commit -am 'Convert hello.rb to DOS' +[whitespace 3270f76] Convert hello.rb to DOS 1 file changed, 7 insertions(+), 7 deletions(-) $ vim hello.rb @@ -65,8 +65,8 @@ index ac51efd..e85207e 100755 hello() -$ git commit -am 'hello mundo change' -[whitespace 6d338d2] hello mundo change +$ git commit -am 'Use Spanish instead of English' +[whitespace 6d338d2] Use Spanish instead of English 1 file changed, 1 insertion(+), 1 deletion(-) ---- @@ -91,8 +91,8 @@ index ac51efd..36c06c8 100755 puts 'hello world' end -$ git commit -am 'document the function' -[master bec6336] document the function +$ git commit -am 'Add comment documenting the function' +[master bec6336] Add comment documenting the function 1 file changed, 1 insertion(+) ---- @@ -312,14 +312,14 @@ For this example, we have two longer lived branches that each have a few commits [source,console] ---- $ git log --graph --oneline --decorate --all -* f1270f7 (HEAD, master) update README -* 9af9d3b add a README -* 694971d update phrase to hola world -| * e3eb223 (mundo) add more tests -| * 7cff591 add testing script -| * c3ffff1 changed text to hello mundo +* f1270f7 (HEAD, master) Update README +* 9af9d3b Create README +* 694971d Update phrase to 'hola world' +| * e3eb223 (mundo) Add more tests +| * 7cff591 Create initial testing script +| * c3ffff1 Change text to 'hello mundo' |/ -* b7dcc89 initial hello world code +* b7dcc89 Initial hello world code ---- We now have three unique commits that live only on the `master` branch and three others that live on the `mundo` branch. @@ -357,7 +357,7 @@ Let's explore a couple of tools that you now have at your disposal to determine Perhaps it's not obvious how exactly you should fix this conflict. You need more context. -One helpful tool is `git checkout` with the `--conflict' option. +One helpful tool is `git checkout` with the `--conflict` option. This will re-checkout the file again and replace the merge conflict markers. This can be useful if you want to reset the markers and try to resolve them again. @@ -397,7 +397,7 @@ $ git config --global merge.conflictstyle diff3 The `git checkout` command can also take `--ours` and `--theirs` options, which can be a really fast way of just choosing either one side or the other without merging things at all. -This can be particularly useful for conflicts of binary files where you can simply choose one side, or where you only want to merge certain files in from another branch - you can do the merge and then checkout certain files from one side or the other before committing. +This can be particularly useful for conflicts of binary files where you can simply choose one side, or where you only want to merge certain files in from another branch -- you can do the merge and then checkout certain files from one side or the other before committing. [[_merge_log]] ===== Merge Log @@ -406,17 +406,17 @@ Another useful tool when resolving merge conflicts is `git log`. This can help you get context on what may have contributed to the conflicts. Reviewing a little bit of history to remember why two lines of development were touching the same area of code can be really helpful sometimes. -To get a full list of all of the unique commits that were included in either branch involved in this merge, we can use the ``triple dot'' syntax that we learned in <<_triple_dot>>. +To get a full list of all of the unique commits that were included in either branch involved in this merge, we can use the ``triple dot'' syntax that we learned in <>. [source,console] ---- $ git log --oneline --left-right HEAD...MERGE_HEAD -< f1270f7 update README -< 9af9d3b add a README -< 694971d update phrase to hola world -> e3eb223 add more tests -> 7cff591 add testing script -> c3ffff1 changed text to hello mundo +< f1270f7 Update README +< 9af9d3b Create README +< 694971d Update phrase to 'hola world' +> e3eb223 Add more tests +> 7cff591 Create initial testing script +> c3ffff1 Change text to 'hello mundo' ---- That's a nice list of the six total commits involved, as well as which line of development each commit was on. @@ -427,8 +427,8 @@ If we add the `--merge` option to `git log`, it will only show the commits in ei [source,console] ---- $ git log --oneline --left-right --merge -< 694971d update phrase to hola world -> c3ffff1 changed text to hello mundo +< 694971d Update phrase to 'hola world' +> c3ffff1 Change text to 'hello mundo' ---- If you run that with the `-p` option instead, you get just the diffs to the file that ended up in conflict. @@ -547,7 +547,7 @@ In most cases, if you follow the errant `git merge` with `git reset --hard HEAD~ .History after `git reset --hard HEAD~` image::images/undomerge-reset.png[History after `git reset --hard HEAD~`.] -We covered `reset` back in <<_git_reset>>, so it shouldn't be too hard to figure out what's going on here. +We covered `reset` back in <>, so it shouldn't be too hard to figure out what's going on here. Here's a quick refresher: `reset --hard` usually goes through three steps: . Move the branch HEAD points to. @@ -556,7 +556,7 @@ Here's a quick refresher: `reset --hard` usually goes through three steps: . Make the working directory look like the index. The downside of this approach is that it's rewriting history, which can be problematic with a shared repository. -Check out <<_rebase_peril>> for more on what can happen; the short version is that if other people have the commits you're rewriting, you should probably avoid `reset`. +Check out <> for more on what can happen; the short version is that if other people have the commits you're rewriting, you should probably avoid `reset`. This approach also won't work if any other commits have been created since the merge; moving the refs would effectively lose those changes. [[_reverse_commit]] diff --git a/book/07-git-tools/sections/bundling.asc b/book/07-git-tools/sections/bundling.asc index 489f455f0..3f1c8212d 100644 --- a/book/07-git-tools/sections/bundling.asc +++ b/book/07-git-tools/sections/bundling.asc @@ -23,13 +23,13 @@ commit 9a466c572fe88b195efd356c3f2bbeccdb504102 Author: Scott Chacon Date: Wed Mar 10 07:34:10 2010 -0800 - second commit + Second commit commit b1ec3248f39900d2a406049d762aa68e9641be25 Author: Scott Chacon Date: Wed Mar 10 07:34:01 2010 -0800 - first commit + First commit ---- If you want to send that repository to someone and you don't have access to a repository to push to, or simply don't want to set one up, you can bundle it with `git bundle create`. @@ -60,8 +60,8 @@ Cloning into 'repo'... ... $ cd repo $ git log --oneline -9a466c5 second commit -b1ec324 first commit +9a466c5 Second commit +b1ec324 First commit ---- If you don't include HEAD in the references, you have to also specify `-b master` or whatever branch is included because otherwise it won't know what branch to check out. @@ -71,11 +71,11 @@ Now let's say you do three commits on it and want to send the new commits back v [source,console] ---- $ git log --oneline -71b84da last commit - second repo -c99cf5b fourth commit - second repo -7011d3d third commit - second repo -9a466c5 second commit -b1ec324 first commit +71b84da Last commit - second repo +c99cf5b Fourth commit - second repo +7011d3d Third commit - second repo +9a466c5 Second commit +b1ec324 First commit ---- First we need to determine the range of commits we want to include in the bundle. @@ -83,16 +83,16 @@ Unlike the network protocols which figure out the minimum set of data to transfe Now, you could just do the same thing and bundle the entire repository, which will work, but it's better to just bundle up the difference - just the three commits we just made locally. In order to do that, you'll have to calculate the difference. -As we described in <<_commit_ranges>>, you can specify a range of commits in a number of ways. -To get the three commits that we have in our master branch that weren't in the branch we originally cloned, we can use something like `origin/master..master` or `master ^origin/master`. +As we described in <>, you can specify a range of commits in a number of ways. +To get the three commits that we have in our `master` branch that weren't in the branch we originally cloned, we can use something like `origin/master..master` or `master ^origin/master`. You can test that with the `log` command. [source,console] ---- $ git log --oneline master ^origin/master -71b84da last commit - second repo -c99cf5b fourth commit - second repo -7011d3d third commit - second repo +71b84da Last commit - second repo +c99cf5b Fourth commit - second repo +7011d3d Third commit - second repo ---- So now that we have the list of commits we want to include in the bundle, let's bundle them up. @@ -131,7 +131,7 @@ The `verify` command would have looked like this instead: ---- $ git bundle verify ../commits-bad.bundle error: Repository lacks these prerequisite commits: -error: 7011d3d8fc200abe0ad561c011c3852a4b7bbe95 third commit - second repo +error: 7011d3d8fc200abe0ad561c011c3852a4b7bbe95 Third commit - second repo ---- However, our first bundle is valid, so we can fetch in commits from it. @@ -145,7 +145,7 @@ $ git bundle list-heads ../commits.bundle The `verify` sub-command will tell you the heads as well. The point is to see what can be pulled in, so you can use the `fetch` or `pull` commands to import commits from this bundle. -Here we'll fetch the 'master' branch of the bundle to a branch named 'other-master' in our repository: +Here we'll fetch the `master` branch of the bundle to a branch named `other-master` in our repository: [source,console] ---- @@ -154,18 +154,18 @@ From ../commits.bundle * [new branch] master -> other-master ---- -Now we can see that we have the imported commits on the 'other-master' branch as well as any commits we've done in the meantime in our own 'master' branch. +Now we can see that we have the imported commits on the `other-master` branch as well as any commits we've done in the meantime in our own `master` branch. [source,console] ---- $ git log --oneline --decorate --graph --all -* 8255d41 (HEAD, master) third commit - first repo -| * 71b84da (other-master) last commit - second repo -| * c99cf5b fourth commit - second repo -| * 7011d3d third commit - second repo +* 8255d41 (HEAD, master) Third commit - first repo +| * 71b84da (other-master) Last commit - second repo +| * c99cf5b Fourth commit - second repo +| * 7011d3d Third commit - second repo |/ -* 9a466c5 second commit -* b1ec324 first commit +* 9a466c5 Second commit +* b1ec324 First commit ---- So, `git bundle` can be really useful for sharing or doing network-type operations when you don't have the proper network or shared repository to do so. diff --git a/book/07-git-tools/sections/credentials.asc b/book/07-git-tools/sections/credentials.asc index 9e74ff08a..7ff7826a9 100644 --- a/book/07-git-tools/sections/credentials.asc +++ b/book/07-git-tools/sections/credentials.asc @@ -168,7 +168,8 @@ Here's the full source code of our new credential helper: include::../git-credential-read-only[] -------- -<1> Here we parse the command-line options, allowing the user to specify the input file. The default is `~/.git-credentials`. +<1> Here we parse the command-line options, allowing the user to specify the input file. + The default is `~/.git-credentials`. <2> This program only responds if the action is `get` and the backing-store file exists. <3> This loop reads from stdin until the first blank line is reached. The inputs are stored in the `known` hash for later reference. diff --git a/book/07-git-tools/sections/debugging.asc b/book/07-git-tools/sections/debugging.asc index 093de5713..bc9d4cad8 100644 --- a/book/07-git-tools/sections/debugging.asc +++ b/book/07-git-tools/sections/debugging.asc @@ -35,12 +35,12 @@ Notice that the first field is the partial SHA-1 of the commit that last modifie The next two fields are values extracted from that commit -- the author name and the authored date of that commit -- so you can easily see who modified that line and when. After that come the line number and the content of the file. Also note the `^1da177e4c3f4` commit lines, where the `^` prefix designates lines that were introduced in the repository's initial commit and have remained unchanged ever since. -This is a tad confusing, because now you’ve seen at least three different ways that Git uses the `^` to modify a commit SHA-1, but that is what it means here. +This is a tad confusing, because now you've seen at least three different ways that Git uses the `^` to modify a commit SHA-1, but that is what it means here. -Another cool thing about Git is that it doesn’t track file renames explicitly. +Another cool thing about Git is that it doesn't track file renames explicitly. It records the snapshots and then tries to figure out what was renamed implicitly, after the fact. One of the interesting features of this is that you can ask it to figure out all sorts of code movement as well. -If you pass `-C` to `git blame`, Git analyzes the file you’re annotating and tries to figure out where snippets of code within it originally came from if they were copied from elsewhere. +If you pass `-C` to `git blame`, Git analyzes the file you're annotating and tries to figure out where snippets of code within it originally came from if they were copied from elsewhere. For example, say you are refactoring a file named `GITServerHandler.m` into multiple files, one of which is `GITPackUpload.m`. By blaming `GITPackUpload.m` with the `-C` option, you can see where sections of the code originally came from: @@ -70,13 +70,13 @@ Git tells you the original commit where you wrote those lines, even if it was in ==== Binary Search Annotating a file helps if you know where the issue is to begin with. -If you don’t know what is breaking, and there have been dozens or hundreds of commits since the last state where you know the code worked, you’ll likely turn to `git bisect` for help. +If you don't know what is breaking, and there have been dozens or hundreds of commits since the last state where you know the code worked, you'll likely turn to `git bisect` for help. The `bisect` command does a binary search through your commit history to help you identify as quickly as possible which commit introduced an issue. -Let’s say you just pushed out a release of your code to a production environment, you’re getting bug reports about something that wasn’t happening in your development environment, and you can’t imagine why the code is doing that. -You go back to your code, and it turns out you can reproduce the issue, but you can’t figure out what is going wrong. +Let's say you just pushed out a release of your code to a production environment, you're getting bug reports about something that wasn't happening in your development environment, and you can't imagine why the code is doing that. +You go back to your code, and it turns out you can reproduce the issue, but you can't figure out what is going wrong. You can _bisect_ the code to find out. -First you run `git bisect start` to get things going, and then you use `git bisect bad` to tell the system that the current commit you’re on is broken. +First you run `git bisect start` to get things going, and then you use `git bisect bad` to tell the system that the current commit you're on is broken. Then, you must tell bisect when the last known good state was, using `git bisect good `: [source,console] @@ -85,29 +85,29 @@ $ git bisect start $ git bisect bad $ git bisect good v1.0 Bisecting: 6 revisions left to test after this -[ecb6e1bc347ccecc5f9350d878ce677feb13d3b2] error handling on repo +[ecb6e1bc347ccecc5f9350d878ce677feb13d3b2] Error handling on repo ---- Git figured out that about 12 commits came between the commit you marked as the last good commit (v1.0) and the current bad version, and it checked out the middle one for you. At this point, you can run your test to see if the issue exists as of this commit. -If it does, then it was introduced sometime before this middle commit; if it doesn’t, then the problem was introduced sometime after the middle commit. +If it does, then it was introduced sometime before this middle commit; if it doesn't, then the problem was introduced sometime after the middle commit. It turns out there is no issue here, and you tell Git that by typing `git bisect good` and continue your journey: [source,console] ---- $ git bisect good Bisecting: 3 revisions left to test after this -[b047b02ea83310a70fd603dc8cd7a6cd13d15c04] secure this thing +[b047b02ea83310a70fd603dc8cd7a6cd13d15c04] Secure this thing ---- -Now you’re on another commit, halfway between the one you just tested and your bad commit. +Now you're on another commit, halfway between the one you just tested and your bad commit. You run your test again and find that this commit is broken, so you tell Git that with `git bisect bad`: [source,console] ---- $ git bisect bad Bisecting: 1 revisions left to test after this -[f71ce38690acf49c1f3c9bea38e09d82a5ce6014] drop exceptions table +[f71ce38690acf49c1f3c9bea38e09d82a5ce6014] Drop exceptions table ---- This commit is fine, and now Git has all the information it needs to determine where the issue was introduced. @@ -121,13 +121,13 @@ commit b047b02ea83310a70fd603dc8cd7a6cd13d15c04 Author: PJ Hyett Date: Tue Jan 27 14:48:32 2009 -0800 - secure this thing + Secure this thing :040000 040000 40ee3e7821b895e52c1695092db9bdc4c61d1730 f24d3c6ebcfc639b1a3814550e62d60b8e68a8e4 M config ---- -When you’re finished, you should run `git bisect reset` to reset your HEAD to where you were before you started, or you’ll end up in a weird state: +When you're finished, you should run `git bisect reset` to reset your HEAD to where you were before you started, or you'll end up in a weird state: [source,console] ---- diff --git a/book/07-git-tools/sections/interactive-staging.asc b/book/07-git-tools/sections/interactive-staging.asc index 094fdb116..affa704b2 100644 --- a/book/07-git-tools/sections/interactive-staging.asc +++ b/book/07-git-tools/sections/interactive-staging.asc @@ -1,9 +1,9 @@ [[_interactive_staging]] === Interactive Staging -In this section, you’ll look at a few interactive Git commands that can help you easily craft your commits to include only certain combinations and parts of files. -These tools are helpful if you modify a number of files and then decide that you want those changes to be in several focused commits rather than one big messy commit. -This way, you can make sure your commits are logically separate changesets and can be easily reviewed by the developers working with you. +In this section, you'll look at a few interactive Git commands that can help you craft your commits to include only certain combinations and parts of files. +These tools are helpful if you modify a number of files extensively, then decide that you want those changes to be partitioned into several focused commits rather than one big messy commit. +This way, you can make sure your commits are logically separate changesets and can be reviewed easily by the developers working with you. If you run `git add` with the `-i` or `--interactive` option, Git enters an interactive shell mode, displaying something like this: @@ -16,23 +16,23 @@ $ git add -i 3: unchanged +5/-1 lib/simplegit.rb *** Commands *** - 1: status 2: update 3: revert 4: add untracked - 5: patch 6: diff 7: quit 8: help + 1: [s]tatus 2: [u]pdate 3: [r]evert 4: [a]dd untracked + 5: [p]atch 6: [d]iff 7: [q]uit 8: [h]elp What now> ---- You can see that this command shows you a much different view of your staging area than you're probably used to -- basically, the same information you get with `git status` but a bit more succinct and informative. -It lists the changes you’ve staged on the left and unstaged changes on the right. +It lists the changes you've staged on the left and unstaged changes on the right. After this comes a ``Commands'' section, which allows you to do a number of things like staging and unstaging files, staging parts of files, adding untracked files, and displaying diffs of what has been staged. ==== Staging and Unstaging Files -If you type `2` or `u` at the `What now>` prompt, you're prompted for which files you want to stage: +If you type `u` or `2` (for update) at the `What now>` prompt, you're prompted for which files you want to stage: [source,console] ---- -What now> 2 +What now> u staged unstaged path 1: unchanged +0/-1 TODO 2: unchanged +1/-1 index.html @@ -61,9 +61,9 @@ Update>> updated 2 paths *** Commands *** - 1: status 2: update 3: revert 4: add untracked - 5: patch 6: diff 7: quit 8: help -What now> 1 + 1: [s]tatus 2: [u]pdate 3: [r]evert 4: [a]dd untracked + 5: [p]atch 6: [d]iff 7: [q]uit 8: [h]elp +What now> s staged unstaged path 1: +0/-1 nothing TODO 2: +1/-1 nothing index.html @@ -71,14 +71,14 @@ What now> 1 ---- Now you can see that the `TODO` and `index.html` files are staged and the `simplegit.rb` file is still unstaged. -If you want to unstage the `TODO` file at this point, you use the `3` or `r` (for revert) option: +If you want to unstage the `TODO` file at this point, you use the `r` or `3` (for revert) option: [source,console] ---- *** Commands *** - 1: status 2: update 3: revert 4: add untracked - 5: patch 6: diff 7: quit 8: help -What now> 3 + 1: [s]tatus 2: [u]pdate 3: [r]evert 4: [a]dd untracked + 5: [p]atch 6: [d]iff 7: [q]uit 8: [h]elp +What now> r staged unstaged path 1: +0/-1 nothing TODO 2: +1/-1 nothing index.html @@ -92,30 +92,30 @@ Revert>> [enter] reverted one path ---- -Looking at your Git status again, you can see that you’ve unstaged the `TODO` file: +Looking at your Git status again, you can see that you've unstaged the `TODO` file: [source,console] ---- *** Commands *** - 1: status 2: update 3: revert 4: add untracked - 5: patch 6: diff 7: quit 8: help -What now> 1 + 1: [s]tatus 2: [u]pdate 3: [r]evert 4: [a]dd untracked + 5: [p]atch 6: [d]iff 7: [q]uit 8: [h]elp +What now> s staged unstaged path 1: unchanged +0/-1 TODO 2: +1/-1 nothing index.html 3: unchanged +5/-1 lib/simplegit.rb ---- -To see the diff of what you’ve staged, you can use the `6` or `d` (for diff) command. +To see the diff of what you've staged, you can use the `d` or `6` (for diff) command. It shows you a list of your staged files, and you can select the ones for which you would like to see the staged diff. This is much like specifying `git diff --cached` on the command line: [source,console] ---- *** Commands *** - 1: status 2: update 3: revert 4: add untracked - 5: patch 6: diff 7: quit 8: help -What now> 6 + 1: [s]tatus 2: [u]pdate 3: [r]evert 4: [a]dd untracked + 5: [p]atch 6: [d]iff 7: [q]uit 8: [h]elp +What now> d staged unstaged path 1: +1/-1 nothing index.html Review diff>> 1 @@ -137,9 +137,9 @@ With these basic commands, you can use the interactive add mode to deal with you ==== Staging Patches -It’s also possible for Git to stage certain _parts_ of files and not the rest. +It's also possible for Git to stage certain _parts_ of files and not the rest. For example, if you make two changes to your `simplegit.rb` file and want to stage one of them and not the other, doing so is very easy in Git. -From the same interactive prompt explained in the previous section, type `5` or `p` (for patch). +From the same interactive prompt explained in the previous section, type `p` or `5` (for patch). Git will ask you which files you would like to partially stage; then, for each section of the selected files, it will display hunks of the file diff and ask if you would like to stage them, one by one: [source,console] @@ -181,7 +181,7 @@ e - manually edit the current hunk ? - print help ---- -Generally, you’ll type `y` or `n` if you want to stage each hunk, but staging all of them in certain files or skipping a hunk decision until later can be helpful too. +Generally, you'll type `y` or `n` if you want to stage each hunk, but staging all of them in certain files or skipping a hunk decision until later can be helpful too. If you stage one part of the file and leave another part unstaged, your status output will look like this: [source,console] @@ -195,10 +195,10 @@ What now> 1 The status of the `simplegit.rb` file is interesting. It shows you that a couple of lines are staged and a couple are unstaged. -You’ve partially staged this file. +You've partially staged this file. At this point, you can exit the interactive adding script and run `git commit` to commit the partially staged files. -You also don’t need to be in interactive add mode to do the partial-file staging -- you can start the same script by using `git add -p` or `git add --patch` on the command line. +You also don't need to be in interactive add mode to do the partial-file staging -- you can start the same script by using `git add -p` or `git add --patch` on the command line. Furthermore, you can use patch mode for partially resetting files with the `git reset --patch` command, for checking out parts of files with the `git checkout --patch` command and for stashing parts of files with the `git stash save --patch` command. We'll go into more details on each of these as we get to more advanced usages of these commands. diff --git a/book/07-git-tools/sections/replace.asc b/book/07-git-tools/sections/replace.asc index 321f48459..ffd08203e 100644 --- a/book/07-git-tools/sections/replace.asc +++ b/book/07-git-tools/sections/replace.asc @@ -18,11 +18,11 @@ We'll use a simple repository with five simple commits: [source,console] ---- $ git log --oneline -ef989d8 fifth commit -c6e1e95 fourth commit -9c68fdc third commit -945704c second commit -c1822cf first commit +ef989d8 Fifth commit +c6e1e95 Fourth commit +9c68fdc Third commit +945704c Second commit +c1822cf First commit ---- We want to break this up into two lines of history. @@ -31,17 +31,17 @@ The second line will just be commits four and five - that will be the recent his image::images/replace1.png[] -Well, creating the historical history is easy, we can just put a branch in the history and then push that branch to the master branch of a new remote repository. +Well, creating the historical history is easy, we can just put a branch in the history and then push that branch to the `master` branch of a new remote repository. [source,console] ---- $ git branch history c6e1e95 $ git log --oneline --decorate -ef989d8 (HEAD, master) fifth commit -c6e1e95 (history) fourth commit -9c68fdc third commit -945704c second commit -c1822cf first commit +ef989d8 (HEAD, master) Fifth commit +c6e1e95 (history) Fourth commit +9c68fdc Third commit +945704c Second commit +c1822cf First commit ---- image::images/replace2.png[] @@ -69,11 +69,11 @@ We need an overlap so we can replace a commit in one with an equivalent commit i [source,console] ---- $ git log --oneline --decorate -ef989d8 (HEAD, master) fifth commit -c6e1e95 (history) fourth commit -9c68fdc third commit -945704c second commit -c1822cf first commit +ef989d8 (HEAD, master) Fifth commit +c6e1e95 (history) Fourth commit +9c68fdc Third commit +945704c Second commit +c1822cf First commit ---- It's useful in this case to create a base commit that has instructions on how to expand the history, so other developers know what to do if they hit the first commit in the truncated history and need more. @@ -85,7 +85,7 @@ We can create our base commit using the `commit-tree` command, which just takes [source,console] ---- -$ echo 'get history from blah blah blah' | git commit-tree 9c68fdc^{tree} +$ echo 'Get history from blah blah blah' | git commit-tree 9c68fdc^{tree} 622e88e9cbfbacfb75b5279245b9fb38dfea10cf ---- @@ -94,7 +94,7 @@ $ echo 'get history from blah blah blah' | git commit-tree 9c68fdc^{tree} The `commit-tree` command is one of a set of commands that are commonly referred to as 'plumbing' commands. These are commands that are not generally meant to be used directly, but instead are used by *other* Git commands to do smaller jobs. On occasions when we're doing weirder things like this, they allow us to do really low-level things but are not meant for daily use. -You can read more about plumbing commands in <<_plumbing_porcelain>> +You can read more about plumbing commands in <> ===== image::images/replace3.png[] @@ -124,9 +124,9 @@ $ git clone https://github.com/schacon/project $ cd project $ git log --oneline master -e146b5f fifth commit -81a708d fourth commit -622e88e get history from blah blah blah +e146b5f Fifth commit +81a708d Fourth commit +622e88e Get history from blah blah blah $ git remote add project-history https://github.com/schacon/project-history $ git fetch project-history @@ -139,19 +139,19 @@ Now the collaborator would have their recent commits in the `master` branch and [source,console] ---- $ git log --oneline master -e146b5f fifth commit -81a708d fourth commit -622e88e get history from blah blah blah +e146b5f Fifth commit +81a708d Fourth commit +622e88e Get history from blah blah blah $ git log --oneline project-history/master -c6e1e95 fourth commit -9c68fdc third commit -945704c second commit -c1822cf first commit +c6e1e95 Fourth commit +9c68fdc Third commit +945704c Second commit +c1822cf First commit ---- To combine them, you can simply call `git replace` with the commit you want to replace and then the commit you want to replace it with. -So we want to replace the "fourth" commit in the master branch with the "fourth" commit in the `project-history/master` branch: +So we want to replace the "fourth" commit in the `master` branch with the "fourth" commit in the `project-history/master` branch: [source,console] ---- @@ -163,11 +163,11 @@ Now, if you look at the history of the `master` branch, it appears to look like [source,console] ---- $ git log --oneline master -e146b5f fifth commit -81a708d fourth commit -9c68fdc third commit -945704c second commit -c1822cf first commit +e146b5f Fifth commit +81a708d Fourth commit +9c68fdc Third commit +945704c Second commit +c1822cf First commit ---- Cool, right? Without having to change all the SHA-1s upstream, we were able to replace one commit in our history with an entirely different commit and all the normal tools (`bisect`, `blame`, etc) will work how we would expect them to. diff --git a/book/07-git-tools/sections/rerere.asc b/book/07-git-tools/sections/rerere.asc index ea0c89c7f..648a9120a 100644 --- a/book/07-git-tools/sections/rerere.asc +++ b/book/07-git-tools/sections/rerere.asc @@ -1,4 +1,4 @@ -[[_rerere]] +[[ref_rerere]] === Rerere The `git rerere` functionality is a bit of a hidden feature. @@ -145,8 +145,8 @@ You can see that it "Recorded resolution for FILE". image::images/rerere2.png[] -Now, let's undo that merge and then rebase it on top of our master branch instead. -We can move our branch back by using `git reset` as we saw in <<_git_reset>>. +Now, let's undo that merge and then rebase it on top of our `master` branch instead. +We can move our branch back by using `git reset` as we saw in <>. [source,console] ---- @@ -224,7 +224,7 @@ def hello end ---- -We saw an example of this in <<_advanced_merging>>. +We saw an example of this in <>. For now though, let's re-resolve it by just running `git rerere` again: [source,console] @@ -249,4 +249,4 @@ $ git rebase --continue Applying: i18n one word ---- -So, if you do a lot of re-merges, or want to keep a topic branch up to date with your master branch without a ton of merges, or you rebase often, you can turn on `rerere` to help your life out a bit. +So, if you do a lot of re-merges, or want to keep a topic branch up to date with your `master` branch without a ton of merges, or you rebase often, you can turn on `rerere` to help your life out a bit. diff --git a/book/07-git-tools/sections/reset.asc b/book/07-git-tools/sections/reset.asc index b9403c831..c7002ac8c 100644 --- a/book/07-git-tools/sections/reset.asc +++ b/book/07-git-tools/sections/reset.asc @@ -51,7 +51,7 @@ The Git `cat-file` and `ls-tree` commands are ``plumbing'' commands that are use [[_the_index]] ===== The Index -The Index is your *proposed next commit*. +The _index_ is your *proposed next commit*. We've also been referring to this concept as Git's ``Staging Area'' as this is what Git looks at when you run `git commit`. Git populates this index with a list of all the file contents that were last checked out into your working directory and what they looked like when they were originally checked out. @@ -71,10 +71,10 @@ The index is not technically a tree structure -- it's actually implemented as a ===== The Working Directory -Finally, you have your working directory. +Finally, you have your _working directory_ (also commonly referred to as the ``working tree''). The other two trees store their content in an efficient but inconvenient manner, inside the `.git` folder. -The Working Directory unpacks them into actual files, which makes it much easier for you to edit them. -Think of the Working Directory as a *sandbox*, where you can try changes out before committing them to your staging area (index) and then to history. +The working directory unpacks them into actual files, which makes it much easier for you to edit them. +Think of the working directory as a *sandbox*, where you can try changes out before committing them to your staging area (index) and then to history. [source,console] ---- @@ -90,40 +90,40 @@ $ tree ==== The Workflow -Git's main purpose is to record snapshots of your project in successively better states, by manipulating these three trees. +Git's typical workflow is to record snapshots of your project in successively better states, by manipulating these three trees. image::images/reset-workflow.png[] Let's visualize this process: say you go into a new directory with a single file in it. We'll call this *v1* of the file, and we'll indicate it in blue. -Now we run `git init`, which will create a Git repository with a HEAD reference which points to an unborn branch (`master` doesn't exist yet). +Now we run `git init`, which will create a Git repository with a HEAD reference which points to the unborn `master` branch. image::images/reset-ex1.png[] -At this point, only the Working Directory tree has any content. +At this point, only the working directory tree has any content. -Now we want to commit this file, so we use `git add` to take content in the Working Directory and copy it to the Index. +Now we want to commit this file, so we use `git add` to take content in the working directory and copy it to the index. image::images/reset-ex2.png[] -Then we run `git commit`, which takes the contents of the Index and saves it as a permanent snapshot, creates a commit object which points to that snapshot, and updates `master` to point to that commit. +Then we run `git commit`, which takes the contents of the index and saves it as a permanent snapshot, creates a commit object which points to that snapshot, and updates `master` to point to that commit. image::images/reset-ex3.png[] If we run `git status`, we'll see no changes, because all three trees are the same. Now we want to make a change to that file and commit it. -We'll go through the same process; first we change the file in our working directory. +We'll go through the same process; first, we change the file in our working directory. Let's call this *v2* of the file, and indicate it in red. image::images/reset-ex4.png[] -If we run `git status` right now, we'll see the file in red as ``Changes not staged for commit,'' because that entry differs between the Index and the Working Directory. -Next we run `git add` on it to stage it into our Index. +If we run `git status` right now, we'll see the file in red as ``Changes not staged for commit'', because that entry differs between the index and the working directory. +Next we run `git add` on it to stage it into our index. image::images/reset-ex5.png[] -At this point, if we run `git status`, we will see the file in green under ``Changes to be committed'' because the Index and HEAD differ -- that is, our proposed next commit is now different from our last commit. +At this point, if we run `git status`, we will see the file in green under ``Changes to be committed'' because the index and HEAD differ -- that is, our proposed next commit is now different from our last commit. Finally, we run `git commit` to finalize the commit. image::images/reset-ex6.png[] @@ -131,7 +131,7 @@ image::images/reset-ex6.png[] Now `git status` will give us no output, because all three trees are the same again. Switching branches or cloning goes through a similar process. -When you checkout a branch, it changes *HEAD* to point to the new branch ref, populates your *Index* with the snapshot of that commit, then copies the contents of the *Index* into your *Working Directory*. +When you checkout a branch, it changes *HEAD* to point to the new branch ref, populates your *index* with the snapshot of that commit, then copies the contents of the *index* into your *working Directory*. ==== The Role of Reset @@ -159,14 +159,14 @@ With `reset --soft`, it will simply stop there. Now take a second to look at that diagram and realize what happened: it essentially undid the last `git commit` command. When you run `git commit`, Git creates a new commit and moves the branch that HEAD points to up to it. -When you `reset` back to `HEAD~` (the parent of HEAD), you are moving the branch back to where it was, without changing the Index or Working Directory. -You could now update the Index and run `git commit` again to accomplish what `git commit --amend` would have done (see <<_git_amend>>). +When you `reset` back to `HEAD~` (the parent of HEAD), you are moving the branch back to where it was, without changing the index or working directory. +You could now update the index and run `git commit` again to accomplish what `git commit --amend` would have done (see <<_git_amend>>). ===== Step 2: Updating the Index (--mixed) -Note that if you run `git status` now you'll see in green the difference between the Index and what the new HEAD is. +Note that if you run `git status` now you'll see in green the difference between the index and what the new HEAD is. -The next thing `reset` will do is to update the Index with the contents of whatever snapshot HEAD now points to. +The next thing `reset` will do is to update the index with the contents of whatever snapshot HEAD now points to. image::images/reset-mixed.png[] @@ -178,7 +178,7 @@ You rolled back to before you ran all your `git add` and `git commit` commands. ===== Step 3: Updating the Working Directory (--hard) -The third thing that `reset` will do is to make the Working Directory look like the Index. +The third thing that `reset` will do is to make the working directory look like the index. If you use the `--hard` option, it will continue to this stage. image::images/reset-hard.png[] @@ -187,7 +187,7 @@ So let's think about what just happened. You undid your last commit, the `git add` and `git commit` commands, *and* all the work you did in your working directory. It's important to note that this flag (`--hard`) is the only way to make the `reset` command dangerous, and one of the very few cases where Git will actually destroy data. -Any other invocation of `reset` can be pretty easily undone, but the `--hard` option cannot, since it forcibly overwrites files in the Working Directory. +Any other invocation of `reset` can be pretty easily undone, but the `--hard` option cannot, since it forcibly overwrites files in the working directory. In this particular case, we still have the *v3* version of our file in a commit in our Git DB, and we could get it back by looking at our `reflog`, but if we had not committed it, Git still would have overwritten the file and it would be unrecoverable. ===== Recap @@ -195,23 +195,23 @@ In this particular case, we still have the *v3* version of our file in a commit The `reset` command overwrites these three trees in a specific order, stopping when you tell it to: 1. Move the branch HEAD points to _(stop here if `--soft`)_ -2. Make the Index look like HEAD _(stop here unless `--hard`)_ -3. Make the Working Directory look like the Index +2. Make the index look like HEAD _(stop here unless `--hard`)_ +3. Make the working directory look like the index ==== Reset With a Path That covers the behavior of `reset` in its basic form, but you can also provide it with a path to act upon. If you specify a path, `reset` will skip step 1, and limit the remainder of its actions to a specific file or set of files. This actually sort of makes sense -- HEAD is just a pointer, and you can't point to part of one commit and part of another. -But the Index and Working directory _can_ be partially updated, so reset proceeds with steps 2 and 3. +But the index and working directory _can_ be partially updated, so reset proceeds with steps 2 and 3. So, assume we run `git reset file.txt`. This form (since you did not specify a commit SHA-1 or branch, and you didn't specify `--soft` or `--hard`) is shorthand for `git reset --mixed HEAD file.txt`, which will: 1. Move the branch HEAD points to _(skipped)_ -2. Make the Index look like HEAD _(stop here)_ +2. Make the index look like HEAD _(stop here)_ -So it essentially just copies `file.txt` from HEAD to the Index. +So it essentially just copies `file.txt` from HEAD to the index. image::images/reset-path1.png[] @@ -221,15 +221,15 @@ If we look at the diagram for that command and think about what `git add` does, image::images/reset-path2.png[] This is why the output of the `git status` command suggests that you run this to unstage a file. -(See <<_unstaging>> for more on this.) +(See <> for more on this.) We could just as easily not let Git assume we meant ``pull the data from HEAD'' by specifying a specific commit to pull that file version from. We would just run something like `git reset eb43bf file.txt`. image::images/reset-path3.png[] -This effectively does the same thing as if we had reverted the content of the file to *v1* in the Working Directory, ran `git add` on it, then reverted it back to *v3* again (without actually going through all those steps). -If we run `git commit` now, it will record a change that reverts that file back to *v1*, even though we never actually had it in our Working Directory again. +This effectively does the same thing as if we had reverted the content of the file to *v1* in the working directory, ran `git add` on it, then reverted it back to *v3* again (without actually going through all those steps). +If we run `git commit` now, it will record a change that reverts that file back to *v1*, even though we never actually had it in our working directory again. It's also interesting to note that like `git add`, the `reset` command will accept a `--patch` option to unstage content on a hunk-by-hunk basis. So you can selectively unstage or revert content. @@ -268,7 +268,7 @@ Like `reset`, `checkout` manipulates the three trees, and it is a bit different Running `git checkout [branch]` is pretty similar to running `git reset --hard [branch]` in that it updates all three trees for you to look like `[branch]`, but there are two important differences. First, unlike `reset --hard`, `checkout` is working-directory safe; it will check to make sure it's not blowing away files that have changes to them. -Actually, it's a bit smarter than that -- it tries to do a trivial merge in the Working Directory, so all of the files you _haven't_ changed in will be updated. +Actually, it's a bit smarter than that -- it tries to do a trivial merge in the working directory, so all of the files you _haven't_ changed will be updated. `reset --hard`, on the other hand, will simply replace everything across the board without checking. The second important difference is how `checkout` updates HEAD. diff --git a/book/07-git-tools/sections/revision-selection.asc b/book/07-git-tools/sections/revision-selection.asc index 96377cd60..b17972dd1 100644 --- a/book/07-git-tools/sections/revision-selection.asc +++ b/book/07-git-tools/sections/revision-selection.asc @@ -1,8 +1,8 @@ [[_revision_selection]] === Revision Selection -Git allows you to refer to a set of commits or a range of commits in several ways. -They aren’t necessarily obvious but are helpful to know. +Git allows you to refer to a single commit, set of commits, or range of commits in a number of ways. +They aren't necessarily obvious but are helpful to know. ==== Single Revisions @@ -13,7 +13,7 @@ This section outlines the various ways you can refer to any commit. Git is smart enough to figure out what commit you're referring to if you provide the first few characters of the SHA-1 hash, as long as that partial hash is at least four characters long and unambiguous; that is, no other object in the object database can have a hash that begins with the same prefix. -For example, to examine a specific commit where you know you added certain functionality, you might first run `git log` command to locate the commit: +For example, to examine a specific commit where you know you added certain functionality, you might first run the `git log` command to locate the commit: [source,console] ---- @@ -22,7 +22,7 @@ commit 734713bc047d87bf7eac9674765ae793478c50d3 Author: Scott Chacon Date: Fri Jan 2 18:32:33 2009 -0800 - fixed refs handling, added gc auto, updated tests + Fix refs handling, add gc auto, update tests commit d921970aadf03b3cf0e71becdaab3147ba71cdef Merge: 1c002dd... 35cfb2b... @@ -35,7 +35,7 @@ commit 1c002dd4b536e7479fe34593e72e6c6c1819e53b Author: Scott Chacon Date: Thu Dec 11 14:58:32 2008 -0800 - added some blame and merge stuff + Add some blame and merge stuff ---- In this case, say you're interested in the commit whose hash begins with `1c002dd...`. @@ -54,13 +54,13 @@ If you pass `--abbrev-commit` to the `git log` command, the output will use shor [source,console] ---- $ git log --abbrev-commit --pretty=oneline -ca82a6d changed the version number -085bb3b removed unnecessary test code -a11bef0 first commit +ca82a6d Change the version number +085bb3b Remove unnecessary test code +a11bef0 Initial commit ---- Generally, eight to ten characters are more than enough to be unique within a project. -For example, as of October 2017, the Linux kernel (which is a fairly sizable project) has over 700,000 commits and almost six million objects, with no two objects whose SHA-1s are identical in the first 11 characters. +For example, as of February 2019, the Linux kernel (which is a fairly sizable project) has over 875,000 commits and almost seven million objects in its object database, with no two objects whose SHA-1s are identical in the first 12 characters. [NOTE] .A SHORT NOTE ABOUT SHA-1 @@ -70,7 +70,7 @@ A lot of people become concerned at some point that they will, by random happens What then? If you do happen to commit an object that hashes to the same SHA-1 value as a previous _different_ object in your repository, Git will see the previous object already in your Git database, assume it was already written and simply reuse it. -If you try to check out that object again at some point, you’ll always get the data of the first object. +If you try to check out that object again at some point, you'll always get the data of the first object. However, you should be aware of how ridiculously unlikely this scenario is. The SHA-1 digest is 20 bytes or 160 bits. @@ -78,10 +78,10 @@ The number of randomly hashed objects needed to ensure a 50% probability of a si (the formula for determining collision probability is `p = (n(n-1)/2) * (1/2^160))`. 2^80^ is 1.2 x 10^24^ or 1 million billion billion. -That’s 1,200 times the number of grains of sand on the earth. +That's 1,200 times the number of grains of sand on the earth. -Here’s an example to give you an idea of what it would take to get a SHA-1 collision. -If all 6.5 billion humans on Earth were programming, and every second, each one was producing code that was the equivalent of the entire Linux kernel history (3.6 million Git objects) and pushing it into one enormous Git repository, it would take roughly 2 years until that repository contained enough objects to have a 50% probability of a single SHA-1 object collision. +Here's an example to give you an idea of what it would take to get a SHA-1 collision. +If all 6.5 billion humans on Earth were programming, and every second, each one was producing code that was the equivalent of the entire Linux kernel history (6.5 million Git objects) and pushing it into one enormous Git repository, it would take roughly 2 years until that repository contained enough objects to have a 50% probability of a single SHA-1 object collision. Thus, a SHA-1 collision is less likely than every member of your programming team being attacked and killed by wolves in unrelated incidents on the same night. ==== @@ -99,8 +99,8 @@ $ git show topic1 ---- If you want to see which specific SHA-1 a branch points to, or if you want to see what any of these examples boils down to in terms of SHA-1s, you can use a Git plumbing tool called `rev-parse`. -You can see <<_git_internals>> for more information about plumbing tools; basically, `rev-parse` exists for lower-level operations and isn’t designed to be used in day-to-day operations. -However, it can be helpful sometimes when you need to see what’s really going on. +You can see <> for more information about plumbing tools; basically, `rev-parse` exists for lower-level operations and isn't designed to be used in day-to-day operations. +However, it can be helpful sometimes when you need to see what's really going on. Here you can run `rev-parse` on your branch. [source,console] @@ -112,16 +112,16 @@ ca82a6dff817ec66f44342007202690a93763949 [[_git_reflog]] ==== RefLog Shortnames -One of the things Git does in the background while you’re working away is keep a ``reflog'' -- a log of where your HEAD and branch references have been for the last few months. +One of the things Git does in the background while you're working away is keep a ``reflog'' -- a log of where your HEAD and branch references have been for the last few months. You can see your reflog by using `git reflog`: [source,console] ---- $ git reflog -734713b HEAD@{0}: commit: fixed refs handling, added gc auto, updated -d921970 HEAD@{1}: merge phedders/rdocs: Merge made by the 'recursive' stategy. -1c002dd HEAD@{2}: commit: added some blame and merge stuff +734713b HEAD@{0}: commit: Fix refs handling, add gc auto, update tests +d921970 HEAD@{1}: merge phedders/rdocs: Merge made by the 'recursive' strategy. +1c002dd HEAD@{2}: commit: Add some blame and merge stuff 1c36188 HEAD@{3}: rebase -i (squash): updating HEAD 95df984 HEAD@{4}: commit: # This is a combination of two commits. 1c36188 HEAD@{5}: rebase -i (squash): updating HEAD @@ -146,7 +146,7 @@ $ git show master@{yesterday} ---- That would show you where tip of your `master` branch was yesterday. -This technique only works for data that’s still in your reflog, so you can’t use it to look for commits older than a few months. +This technique only works for data that's still in your reflog, so you can't use it to look for commits older than a few months. To see reflog information formatted like the `git log` output, you can run `git log -g`: @@ -155,11 +155,11 @@ To see reflog information formatted like the `git log` output, you can run `git $ git log -g master commit 734713bc047d87bf7eac9674765ae793478c50d3 Reflog: master@{0} (Scott Chacon ) -Reflog message: commit: fixed refs handling, added gc auto, updated +Reflog message: commit: Fix refs handling, add gc auto, update tests Author: Scott Chacon Date: Fri Jan 2 18:32:33 2009 -0800 - fixed refs handling, added gc auto, updated tests + Fix refs handling, add gc auto, update tests commit d921970aadf03b3cf0e71becdaab3147ba71cdef Reflog: master@{1} (Scott Chacon ) @@ -170,8 +170,8 @@ Date: Thu Dec 11 15:08:43 2008 -0800 Merge commit 'phedders/rdocs' ---- -It’s important to note that reflog information is strictly local -- it’s a log only of what _you've_ done in _your_ repository. -The references won’t be the same on someone else’s copy of the repository; also, right after you initially clone a repository, you'll have an empty reflog, as no activity has occurred yet in your repository. +It's important to note that reflog information is strictly local -- it's a log only of what _you've_ done in _your_ repository. +The references won't be the same on someone else's copy of the repository; also, right after you initially clone a repository, you'll have an empty reflog, as no activity has occurred yet in your repository. Running `git show HEAD@{2.months.ago}` will show you the matching commit only if you cloned the project at least two months ago -- if you cloned it any more recently than that, you'll see only your first local commit. [TIP] @@ -189,14 +189,14 @@ Suppose you look at the history of your project: [source,console] ---- $ git log --pretty=format:'%h %s' --graph -* 734713b fixed refs handling, added gc auto, updated tests +* 734713b Fix refs handling, add gc auto, update tests * d921970 Merge commit 'phedders/rdocs' |\ | * 35cfb2b Some rdoc changes -* | 1c002dd added some blame and merge stuff +* | 1c002dd Add some blame and merge stuff |/ -* 1c36188 ignore *.gem -* 9b29157 add open3_detach to gemspec file list +* 1c36188 Ignore *.gem +* 9b29157 Add open3_detach to gemspec file list ---- Then, you can see the previous commit by specifying `HEAD^`, which means ``the parent of HEAD'': @@ -216,7 +216,8 @@ Date: Thu Dec 11 15:08:43 2008 -0800 .Escaping the caret on Windows ==== -On Windows in `cmd.exe`, `^` is a special character and needs to be treated differently. You can either double it or put the commit reference in quotes: +On Windows in `cmd.exe`, `^` is a special character and needs to be treated differently. +You can either double it or put the commit reference in quotes: [source,console] ---- @@ -227,9 +228,8 @@ $ git show "HEAD^" # OK ==== -You can also specify a number after the `^` – for example, `d921970^2` means ``the second parent of d921970.'' -This syntax is useful only for merge commits, which have more than one parent. -The first parent is the branch you were on when you merged, and the second is the commit on the branch that you merged in: +You can also specify a number after the `^` to identify _which_ parent you want; for example, `d921970^2` means ``the second parent of d921970.'' +This syntax is useful only for merge commits, which have more than one parent -- the _first_ parent of a merge commit is from the branch you were on when you merged (frequently `master`), while the _second_ parent of a merge commit is from the branch that was merged (say, `topic`): [source,console] ---- @@ -238,7 +238,7 @@ commit 1c002dd4b536e7479fe34593e72e6c6c1819e53b Author: Scott Chacon Date: Thu Dec 11 14:58:32 2008 -0800 - added some blame and merge stuff + Add some blame and merge stuff $ git show d921970^2 commit 35cfb2b795a55793d7cc56a6cc2060b4bb732548 @@ -261,19 +261,19 @@ commit 1c3618887afb5fbcbea25b7c013f4e2114448b8d Author: Tom Preston-Werner Date: Fri Nov 7 13:47:59 2008 -0500 - ignore *.gem + Ignore *.gem ---- -This can also be written `HEAD^^^`, which again is the first parent of the first parent of the first parent: +This can also be written `HEAD~~~`, which again is the first parent of the first parent of the first parent: [source,console] ---- -$ git show HEAD^^^ +$ git show HEAD~~~ commit 1c3618887afb5fbcbea25b7c013f4e2114448b8d Author: Tom Preston-Werner Date: Fri Nov 7 13:47:59 2008 -0500 - ignore *.gem + Ignore *.gem ---- You can also combine these syntaxes -- you can get the second parent of the previous reference (assuming it was a merge commit) by using `HEAD~3^2`, and so on. @@ -281,21 +281,21 @@ You can also combine these syntaxes -- you can get the second parent of the prev [[_commit_ranges]] ==== Commit Ranges -Now that you can specify individual commits, let’s see how to specify ranges of commits. -This is particularly useful for managing your branches -- if you have a lot of branches, you can use range specifications to answer questions such as, ``What work is on this branch that I haven’t yet merged into my main branch?'' +Now that you can specify individual commits, let's see how to specify ranges of commits. +This is particularly useful for managing your branches -- if you have a lot of branches, you can use range specifications to answer questions such as, ``What work is on this branch that I haven't yet merged into my main branch?'' ===== Double Dot The most common range specification is the double-dot syntax. -This basically asks Git to resolve a range of commits that are reachable from one commit but aren’t reachable from another. +This basically asks Git to resolve a range of commits that are reachable from one commit but aren't reachable from another. For example, say you have a commit history that looks like <>. [[double_dot]] .Example history for range selection. image::images/double-dot.png[Example history for range selection.] -Say you want to see what is in your `experiment` branch that hasn’t yet been merged into your `master` branch. -You can ask Git to show you a log of just those commits with `master..experiment` -- that means ``all commits reachable from experiment that aren’t reachable from master.'' +Say you want to see what is in your `experiment` branch that hasn't yet been merged into your `master` branch. +You can ask Git to show you a log of just those commits with `master..experiment` -- that means ``all commits reachable from `experiment` that aren't reachable from `master`.'' For the sake of brevity and clarity in these examples, the letters of the commit objects from the diagram are used in place of the actual log output in the order that they would display: [source,console] @@ -305,7 +305,7 @@ D C ---- -If, on the other hand, you want to see the opposite -- all commits in `master` that aren’t in `experiment` -- you can reverse the branch names. +If, on the other hand, you want to see the opposite -- all commits in `master` that aren't in `experiment` -- you can reverse the branch names. `experiment..master` shows you everything in `master` not reachable from `experiment`: [source,console] @@ -315,23 +315,23 @@ F E ---- -This is useful if you want to keep the `experiment` branch up to date and preview what you’re about to merge. -Another frequent use of this syntax is to see what you’re about to push to a remote: +This is useful if you want to keep the `experiment` branch up to date and preview what you're about to merge. +Another frequent use of this syntax is to see what you're about to push to a remote: [source,console] ---- $ git log origin/master..HEAD ---- -This command shows you any commits in your current branch that aren’t in the `master` branch on your `origin` remote. +This command shows you any commits in your current branch that aren't in the `master` branch on your `origin` remote. If you run a `git push` and your current branch is tracking `origin/master`, the commits listed by `git log origin/master..HEAD` are the commits that will be transferred to the server. You can also leave off one side of the syntax to have Git assume `HEAD`. For example, you can get the same results as in the previous example by typing `git log origin/master..` -- Git substitutes `HEAD` if one side is missing. ===== Multiple Points -The double-dot syntax is useful as a shorthand, but perhaps you want to specify more than two branches to indicate your revision, such as seeing what commits are in any of several branches that aren’t in the branch you’re currently on. -Git allows you to do this by using either the `^` character or `--not` before any reference from which you don’t want to see reachable commits. +The double-dot syntax is useful as a shorthand, but perhaps you want to specify more than two branches to indicate your revision, such as seeing what commits are in any of several branches that aren't in the branch you're currently on. +Git allows you to do this by using either the `^` character or `--not` before any reference from which you don't want to see reachable commits. Thus, the following three commands are equivalent: [source,console] diff --git a/book/07-git-tools/sections/rewriting-history.asc b/book/07-git-tools/sections/rewriting-history.asc index 6f6db755a..be5c5191a 100644 --- a/book/07-git-tools/sections/rewriting-history.asc +++ b/book/07-git-tools/sections/rewriting-history.asc @@ -3,12 +3,13 @@ Many times, when working with Git, you may want to revise your local commit history. One of the great things about Git is that it allows you to make decisions at the last possible moment. -You can decide what files go into which commits right before you commit with the staging area, you can decide that you didn’t mean to be working on something yet with `git stash`, and you can rewrite commits that already happened so they look like they happened in a different way. +You can decide what files go into which commits right before you commit with the staging area, you can decide that you didn't mean to be working on something yet with `git stash`, and you can rewrite commits that already happened so they look like they happened in a different way. This can involve changing the order of the commits, changing messages or modifying files in a commit, squashing together or splitting apart commits, or removing commits entirely -- all before you share your work with others. -In this section, you’ll see how to accomplish these tasks so that you can make your commit history look the way you want before you share it with others. +In this section, you'll see how to accomplish these tasks so that you can make your commit history look the way you want before you share it with others. [NOTE] +.Don't push your work until you're happy with it ==== One of the cardinal rules of Git is that, since so much work is local within your clone, you have a great deal of freedom to rewrite your history _locally_. However, once you push your work, it is a different story entirely, and you should consider pushed work as final unless you have good reason to change it. @@ -18,8 +19,8 @@ In short, you should avoid pushing your work until you're happy with it and read [[_git_amend]] ==== Changing the Last Commit -Changing your most recent commit is probably the most common rewriting of history that you’ll do. -You’ll often want to do two basic things to your last commit: simply change the commit message, or change the actual content of the commit by adding, removing and modifying files. +Changing your most recent commit is probably the most common rewriting of history that you'll do. +You'll often want to do two basic things to your last commit: simply change the commit message, or change the actual content of the commit by adding, removing and modifying files. If you simply want to modify your last commit message, that's easy: @@ -34,7 +35,7 @@ When you save and close the editor, the editor writes a new commit containing th If, on the other hand, you want to change the actual _content_ of your last commit, the process works basically the same way -- first make the changes you think you forgot, stage those changes, and the subsequent `git commit --amend` _replaces_ that last commit with your new, improved commit. You need to be careful with this technique because amending changes the SHA-1 of the commit. -It’s like a very small rebase -- don’t amend your last commit if you’ve already pushed it. +It's like a very small rebase -- don't amend your last commit if you've already pushed it. [TIP] .An amended commit may (or may not) need an amended commit message @@ -55,39 +56,47 @@ $ git commit --amend --no-edit ==== Changing Multiple Commit Messages To modify a commit that is farther back in your history, you must move to more complex tools. -Git doesn’t have a modify-history tool, but you can use the rebase tool to rebase a series of commits onto the HEAD they were originally based on instead of moving them to another one. +Git doesn't have a modify-history tool, but you can use the rebase tool to rebase a series of commits onto the HEAD they were originally based on instead of moving them to another one. With the interactive rebase tool, you can then stop after each commit you want to modify and change the message, add files, or do whatever you wish. You can run rebase interactively by adding the `-i` option to `git rebase`. You must indicate how far back you want to rewrite commits by telling the command which commit to rebase onto. For example, if you want to change the last three commit messages, or any of the commit messages in that group, you supply as an argument to `git rebase -i` the parent of the last commit you want to edit, which is `HEAD~2^` or `HEAD~3`. -It may be easier to remember the `~3` because you’re trying to edit the last three commits, but keep in mind that you’re actually designating four commits ago, the parent of the last commit you want to edit: +It may be easier to remember the `~3` because you're trying to edit the last three commits, but keep in mind that you're actually designating four commits ago, the parent of the last commit you want to edit: [source,console] ---- $ git rebase -i HEAD~3 ---- -Remember again that this is a rebasing command – every commit included in the range `HEAD~3..HEAD` will be rewritten, whether you change the message or not. -Don’t include any commit you’ve already pushed to a central server – doing so will confuse other developers by providing an alternate version of the same change. +Remember again that this is a rebasing command -- every commit in the range `HEAD~3..HEAD` with a changed message _and all of its descendants_ will be rewritten. +Don't include any commit you've already pushed to a central server -- doing so will confuse other developers by providing an alternate version of the same change. Running this command gives you a list of commits in your text editor that looks something like this: [source,console] ---- -pick f7f3f6d changed my name a bit -pick 310154e updated README formatting and added blame -pick a5f4a0d added cat-file +pick f7f3f6d Change my name a bit +pick 310154e Update README formatting and add blame +pick a5f4a0d Add cat-file # Rebase 710f0f8..a5f4a0d onto 710f0f8 # # Commands: -# p, pick = use commit -# r, reword = use commit, but edit the commit message -# e, edit = use commit, but stop for amending -# s, squash = use commit, but meld into previous commit -# f, fixup = like "squash", but discard this commit's log message -# x, exec = run command (the rest of the line) using shell +# p, pick = use commit +# r, reword = use commit, but edit the commit message +# e, edit = use commit, but stop for amending +# s, squash = use commit, but meld into previous commit +# f, fixup = like "squash", but discard this commit's log message +# x, exec = run command (the rest of the line) using shell +# b, break = stop here (continue rebase later with 'git rebase --continue') +# d, drop = remove commit +# l, label