Merge branch 'master' into ortografia-readme

Author: sergiocabral

README.asc

@@ -2,7 +2,7 @@
 
 Bem-vindo à segunda edição do livro Pro Git.
 
-> If you're looking for official version, in English, see https://github.com/progit/progit2[].
+> Se você está procurando pela versão oficial, em Inglês, vá para o link https://github.com/progit/progit2[].
 
 Você pode achar esse livro online em: http://git-scm.com/book
 

book-en/01-introduction/sections/about-version-control.asc

@@ -1,12 +1,12 @@
 === About Version Control
 
 (((version control)))
-What is "version control", and why should you care?
+What is "`version control`", and why should you care?
 Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later.
-For the examples in this book you will use software source code as the files being version controlled, though in reality you can do this with nearly any type of file on a computer.
+For the examples in this book, you will use software source code as the files being version controlled, though in reality you can do this with nearly any type of file on a computer.
 
 If you are a graphic or web designer and want to keep every version of an image or layout (which you would most certainly want to), a Version Control System (VCS) is a very wise thing to use.
-It allows you to revert files back to a previous state, revert the entire project back to a previous state, compare changes over time, see who last modified something that might be causing a problem, who introduced an issue and when, and more.
+It allows you to revert selected files back to a previous state, revert the entire project back to a previous state, compare changes over time, see who last modified something that might be causing a problem, who introduced an issue and when, and more.
 Using a VCS also generally means that if you screw things up or lose files, you can easily recover.
 In addition, you get all this for very little overhead.
 
@@ -19,43 +19,42 @@ It is easy to forget which directory you're in and accidentally write to the wro
 
 To deal with this issue, programmers long ago developed local VCSs that had a simple database that kept all the changes to files under revision control.
 
-.Local version control.
+.Local version control
 image::images/local.png[Local version control diagram]
 
-One of the more popular VCS tools was a system called RCS, which is still distributed with many computers today.
-Even the popular Mac OS X operating system includes the `rcs` command when you install the Developer Tools.
-RCS works by keeping patch sets (that is, the differences between files) in a special format on disk; it can then re-create what any file looked like at any point in time by adding up all the patches.
+One of the most popular VCS tools was a system called RCS, which is still distributed with many computers today.
+https://www.gnu.org/software/rcs/[RCS] works by keeping patch sets (that is, the differences between files) in a special format on disk; it can then re-create what any file looked like at any point in time by adding up all the patches.
 
 ==== Centralized Version Control Systems
 
 (((version control,centralized)))
 The next major issue that people encounter is that they need to collaborate with developers on other systems.
 To deal with this problem, Centralized Version Control Systems (CVCSs) were developed.
-These systems, such as CVS, Subversion, and Perforce, have a single server that contains all the versioned files, and a number of clients that check out files from that central place. (((CVS)))(((Subversion)))(((Perforce)))
+These systems (such as CVS, Subversion, and Perforce) have a single server that contains all the versioned files, and a number of clients that check out files from that central place. (((CVS)))(((Subversion)))(((Perforce)))
 For many years, this has been the standard for version control.
 
-.Centralized version control.
+.Centralized version control
 image::images/centralized.png[Centralized version control diagram]
 
 This setup offers many advantages, especially over local VCSs.
 For example, everyone knows to a certain degree what everyone else on the project is doing.
-Administrators have fine-grained control over who can do what; and it's far easier to administer a CVCS than it is to deal with local databases on every client.
+Administrators have fine-grained control over who can do what, and it's far easier to administer a CVCS than it is to deal with local databases on every client.
 
 However, this setup also has some serious downsides.
 The most obvious is the single point of failure that the centralized server represents.
 If that server goes down for an hour, then during that hour nobody can collaborate at all or save versioned changes to anything they're working on.
-If the hard disk the central database is on becomes corrupted, and proper backups haven't been kept, you lose absolutely everything – the entire history of the project except whatever single snapshots people happen to have on their local machines.
-Local VCS systems suffer from this same problem – whenever you have the entire history of the project in a single place, you risk losing everything.
+If the hard disk the central database is on becomes corrupted, and proper backups haven't been kept, you lose absolutely everything -- the entire history of the project except whatever single snapshots people happen to have on their local machines.
+Local VCSs suffer from this same problem -- whenever you have the entire history of the project in a single place, you risk losing everything.
 
 ==== Distributed Version Control Systems
 
 (((version control,distributed)))
 This is where Distributed Version Control Systems (DVCSs) step in.
-In a DVCS (such as Git, Mercurial, Bazaar or Darcs), clients don't just check out the latest snapshot of the files: they fully mirror the repository.
-Thus if any server dies, and these systems were collaborating via it, any of the client repositories can be copied back up to the server to restore it.
+In a DVCS (such as Git, Mercurial, Bazaar or Darcs), clients don't just check out the latest snapshot of the files; rather, they fully mirror the repository, including its full history.
+Thus, if any server dies, and these systems were collaborating via that server, any of the client repositories can be copied back up to the server to restore it.
 Every clone is really a full backup of all the data.
 
-.Distributed version control.
+.Distributed version control
 image::images/distributed.png[Distributed version control diagram]
 
 Furthermore, many of these systems deal pretty well with having several remote repositories they can work with, so you can collaborate with different groups of people in different ways simultaneously within the same project.

book-en/01-introduction/sections/command-line.asc

@@ -1,11 +1,11 @@
 === The Command Line
 
 There are a lot of different ways to use Git.
-There are the original command line tools, and there are many graphical user interfaces of varying capabilities.
+There are the original command-line tools, and there are many graphical user interfaces of varying capabilities.
 For this book, we will be using Git on the command line.
-For one, the command line is the only place you can run *all* Git commands – most of the GUIs only implement some subset of Git functionality for simplicity.
-If you know how to run the command line version, you can probably also figure out how to run the GUI version, while the opposite is not necessarily true.
+For one, the command line is the only place you can run _all_ Git commands -- most of the GUIs implement only a partial subset of Git functionality for simplicity.
+If you know how to run the command-line version, you can probably also figure out how to run the GUI version, while the opposite is not necessarily true.
 Also, while your choice of graphical client is a matter of personal taste, _all_ users will have the command-line tools installed and available.
 
-So we will expect you to know how to open Terminal in Mac or Command Prompt or Powershell in Windows.
+So we will expect you to know how to open Terminal in macOS or Command Prompt or PowerShell in Windows.
 If you don't know what we're talking about here, you may need to stop and research that quickly so that you can follow the rest of the examples and descriptions in this book.

book-en/01-introduction/sections/first-time-setup.asc

@@ -8,20 +8,30 @@ You can also change them at any time by running through the commands again.
 Git comes with a tool called `git config` that lets you get and set configuration variables that control all aspects of how Git looks and operates.(((git commands, config)))
 These variables can be stored in three different places:
 
-1. `/etc/gitconfig` file: Contains values for every user on the system and all their repositories.
+1. `[path]/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.
-2. `~/.gitconfig` or `~/.config/git/config` file: Specific to your user.
-  You can make Git read and write to this file specifically by passing the `--global` option.
+  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, and this affects _all_ of the repositories you work with on your system.
 3. `config` file in the Git directory (that is, `.git/config`) of whatever repository you're currently using: Specific to that single repository.
+  You can force Git to read from and write to this file with the `--local` option, but that is in fact the default.
+  Unsurprisingly, you need to be located somewhere in a Git repository for this option to work properly.
 
-Each level overrides values in the previous level, so values in `.git/config` trump those in `/etc/gitconfig`.
+Each level overrides values in the previous level, so values in `.git/config` trump those in `[path]/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.
+It also still looks for `[path]/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 <file>` as an admin.
 
+You can view all of your settings and where they are coming from using:
+
+[source,console]
+----
+$ git config --list --show-origin
+----
+
 ==== Your Identity
 
 The first thing you should do when you install Git is to set your user name and email address.
@@ -38,6 +48,7 @@ If you want to override this with a different name or email address for specific
 
 Many of the GUI tools will help you do this when you first run them.
 
+[[_editor]]
 ==== Your Editor
 
 Now that your identity is set up, you can configure the default text editor that will be used when Git needs you to type in a message.
@@ -50,34 +61,44 @@ If you want to use a different text editor, such as Emacs, you can do the follow
 $ git config --global core.editor emacs
 ----
 
-While on a Windows system, if you want to use a different text editor, such as Notepad++, you can do the following:
+On a Windows system, if you want to use a different text editor, you must specify the full path to its executable file.
+This can be different depending on how your editor is packaged.
+
+In the case of Notepad++, a popular programming editor, you are likely to want to use the 32-bit version, since at the time of writing the 64-bit version doesn't support all plug-ins.
+If you are on a 32-bit Windows system, or you have a 64-bit editor on a 64-bit system, you'll type something like this:
 
-On a x86 system
-[source,console]
-----
-$ git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -multiInst -nosession"
-----
-On a x64 system
 [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]
 ====
-Vim, Emacs and Notepad++ are popular text editors often used by developers on Unix based systems like Linux and OS X or a Windows system.
-If you are not familiar with either of these editors, you may need to search for specific instructions for how to set up your favorite editor with Git.
+Vim, Emacs and Notepad++ are popular text editors often used by developers on Unix-based systems like Linux and macOS or a Windows system.
+If you are using another editor, or a 32-bit version, please find specific instructions for how to set up your favorite editor with Git in <<C-git-commands#ch_core_editor>>.
 ====
 
 [WARNING]
 ====
-You may find, if you don't setup an editor like this, you will likely get into a really confusing state when they are launched.
-Such example on a Windows system may include a prematurely terminated Git operation during a Git initiated edit.
+You may find, if you don't setup your editor like this, you get into a really confusing state when Git attempts to launch it.
+An example on a Windows system may include a prematurely terminated Git operation during a Git initiated edit.
 ====
 
+==== Your default branch name
+
+By default Git will create a branch called _master_ when you create a new repository with `git init`.
+From Git version 2.28 onwards, you can set a different name for the initial branch.
+
+To set _main_ as the default branch name do:
+
+[source,console]
+----
+$ git config --global init.defaultBranch main
+----
+
 ==== Checking Your Settings
 
-If you want to check your settings, you can use the `git config --list` command to list all the settings Git can find at that point:
+If you want to check your configuration settings, you can use the `git config --list` command to list all the settings Git can find at that point:
 
 [source,console]
 ----
@@ -91,7 +112,7 @@ color.diff=auto
 ...
 ----
 
-You may see keys more than once, because Git reads the same key from different files (`/etc/gitconfig` and `~/.gitconfig`, for example).
+You may see keys more than once, because Git reads the same key from different files (`[path]/etc/gitconfig` and `~/.gitconfig`, for example).
 In this case, Git uses the last value for each unique key it sees.
 
 You can also check what Git thinks a specific key's value is by typing `git config <key>`:(((git commands, config)))
@@ -101,3 +122,15 @@ You can also check what Git thinks a specific key's value is by typing `git conf
 $ git config user.name
 John Doe
 ----
+
+[NOTE]
+====
+Since Git might read the same configuration variable value from more than one file, it's possible that you have an unexpected value for one of these values and you don't know why.
+In cases like that, you can query Git as to the _origin_ for that value, and it will tell you which configuration file had the final say in setting that value:
+
+[source,console]
+----
+$ git config --show-origin rerere.autoUpdate
+file:/home/johndoe/.gitconfig	false
+----
+====

book-en/01-introduction/sections/help.asc

@@ -1,7 +1,7 @@
 [[_git_help]]
 === Getting Help
 
-If you ever need help while using Git, there are three ways to get the manual page (manpage) help for any of the Git commands:
+If you ever need help while using Git, there are three equivalent ways to get the comprehensive manual page (manpage) help for any of the Git commands:
 
 [source,console]
 ----
@@ -10,13 +10,39 @@ $ git <verb> --help
 $ man git-<verb>
 ----
 
-For example, you can get the manpage help for the config command by running(((git commands, help)))
+For example, you can get the manpage help for the `git config` command by running this:(((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).
+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, which can be found at https://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)))
+
+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` option, as in:
+
+[source,console]
+----
+$ git add -h
+usage: git add [<options>] [--] <pathspec>...
+
+    -n, --dry-run         dry run
+    -v, --verbose         be verbose
+
+    -i, --interactive     interactive picking
+    -p, --patch           select hunks interactively
+    -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
+----
+

book-en/01-introduction/sections/history.asc

@@ -17,4 +17,4 @@ Some of the goals of the new system were as follows:
 *  Able to handle large projects like the Linux kernel efficiently (speed and data size)
 
 Since its birth in 2005, Git has evolved and matured to be easy to use and yet retain these initial qualities.
-It's incredibly fast, it's very efficient with large projects, and it has an incredible branching system for non-linear development (See <<_git_branching>>).
+It's amazingly fast, it's very efficient with large projects, and it has an incredible branching system for non-linear development (See <<ch03-git-branching#ch03-git-branching>>).