Skip to content

Numerous tweaks (rewording/grammar/fonts) to "Maintaining a Project" #891

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 22, 2017
Merged

Numerous tweaks (rewording/grammar/fonts) to "Maintaining a Project" #891

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 19 additions & 12 deletions book/05-distributed-git/sections/maintaining.asc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ There are two ways to apply an emailed patch: with `git apply` or with `git am`.
===== Applying a Patch with apply

(((git commands, apply)))
If you received the patch from someone who generated it with the `git diff` or a Unix `diff` command (which is not recommended; see the next section), you can apply it with the `git apply` command.
If you received the patch from someone who generated it with `git diff` or some variation of the Unix `diff` command (which is not recommended; see the next section), you can apply it with the `git apply` command.
Assuming you saved the patch at `/tmp/patch-ruby-client.patch`, you can apply the patch like this:

[source,console]
Expand Down Expand Up @@ -87,12 +87,11 @@ Subject: [PATCH 1/2] add limit to log function
Limit log functionality to the first 20
----

This is the beginning of the output of the `format-patch` command that you saw in the previous section.
This is also a valid mbox email format.
This is the beginning of the output of the `git format-patch` command that you saw in the previous section; it also represents a valid mbox email format.
If someone has emailed you the patch properly using `git send-email`, and you download that into an mbox format, then you can point `git am` to that mbox file, and it will start applying all the patches it sees.
If you run a mail client that can save several emails out in mbox format, you can save entire patch series into a file and then use `git am` to apply them one at a time.

However, if someone uploaded a patch file generated via `format-patch` to a ticketing system or something similar, you can save the file locally and then pass that file saved on your disk to `git am` to apply it:
However, if someone uploaded a patch file generated via `git format-patch` to a ticketing system or something similar, you can save the file locally and then pass that file saved on your disk to `git am` to apply it:

[source,console]
----
Expand Down Expand Up @@ -264,7 +263,7 @@ 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.
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:
Expand All @@ -276,8 +275,15 @@ $ git merge-base contrib master
$ git diff 36c7db
----

However, that isn't convenient, so Git provides another shorthand for doing the same thing: the triple-dot syntax.
In the context of the `diff` command, you can put three periods after another branch to do a `diff` between the last commit of the branch you're on and its common ancestor with another branch:
or, more concisely:

[source,console]
----
$ git diff $(git merge-base contrib master)
----

However, neither of those is particularly convenient, so Git provides another shorthand for doing the same thing: the triple-dot syntax.
In the context of the `git diff` command, you can put three periods after another branch to do a `diff` between the last commit of the branch you're on and its common ancestor with another branch:

[source,console]
----
Expand All @@ -297,10 +303,11 @@ You have a number of choices, so we'll cover a few of them.
===== Merging Workflows

(((workflows, merging)))
One simple workflow is to merge the work into your `master` branch.
One basic workflow is to simply merge all that work directly into your `master` branch.
In this scenario, you have a `master` branch that contains basically stable code.
When you have work in a topic branch that you've done or that someone has contributed and you've verified, you merge it into your master branch, delete the topic branch, and then continue the process.
If we have a repository with work in two branches named `ruby_client` and `php_client` that looks like <<merwf_a>> and merge `ruby_client` first and then `php_client` next, then your history will end up looking like <<merwf_b>>.
When you have work in a topic branch that you think you've completed, or work that someone else has contributed and you've verified, you merge it into your master branch, delete that just-merged topic branch, and repeat.

For instance, if we have a repository with work in two branches named `ruby_client` and `php_client` that looks like <<merwf_a>>, and we merge `ruby_client` followed by `php_client`, your history will end up looking like <<merwf_b>>.

[[merwf_a]]
.History with several topic branches.
Expand Down Expand Up @@ -329,7 +336,7 @@ image::images/merging-workflows-4.png[After a topic branch merge.]
.After a project release.
image::images/merging-workflows-5.png[After a topic branch release.]

This way, when people clone your project's repository, they can either check out `master` to build the latest stable version and keep up to date on that easily, or they can check out `develop`, which is the more cutting-edge stuff.
This way, when people clone your project's repository, they can either check out `master` to build the latest stable version and keep up to date on that easily, or they can check out `develop`, which is the more cutting-edge content.
You can also extend this concept by having an `integrate` branch where all the work is merged together.
Then, when the codebase on that branch is stable and passes tests, you merge it into a `develop` branch; and when that has proven itself stable for a while, you fast-forward your `master` branch.

Expand Down Expand Up @@ -421,7 +428,7 @@ We will cover rerere in more detail in <<_rerere>>.
==== Tagging Your Releases

(((tags)))(((tags, signing)))
When you've decided to cut a release, you'll probably want to drop a tag so you can re-create that release at any point going forward.
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>>.
If you decide to sign the tag as the maintainer, the tagging may look something like this:

Expand Down