Handling conflicts when making a Pull Request (PR)

This article covers how to resolve git conflicts when making a pull request on DCS, usually due to two people working on the same files in tC-Create.

We will work from an imaginary example. Let’s say my org is “MyOrg” and my username is “richmahn”.

Seeing conflicts on DCS in a PR

I used tC-Create to make a translation of the English translationAcademy (unfoldingWord/en_ta: unfoldingWord® Translation Academy - en_ta - Door43 Content Service) into my target translation of Hindi (git.door43.org/MyOrg/hi_ta).

I made a change multiple files, committing these changes to the richmahn-tc-create-1 branch. After starting my work with tC-create, someone else made changes that got merged into master, and these changes conflicted with 3 of my changed files. I can see this by making a PR with my branch:

So three files conflict:

translate/figs-abstractnouns/sub-title.md
translate/figs-abstractnouns/title.md
translate/figs-apostrophe/01.md

Install Git

To handle this, we need to download and install git if we haven’t already done so, and clone our MyOrg/hi_ta repo locally and merge master from origin (DCS is or origin) into our branch so it no longer conflicts with master and thus can be merged into master.

Resolving Conflicts Locally

Steps:

  1. After downloading git, open a terminal (on Windows a Command prompt and make sure the installed git binaries are in your environment path), and cd to your user directory.

  2. Now we clone our repo (skip this step if you already have cloned it before):

$ git clone git@git.door43.org:MyOrg/hi_ta.git

Cloning into 'hi_ta'...
remote: Enumerating objects: 1428, done.
remote: Counting objects: 100% (1428/1428), done.
remote: Compressing objects: 100% (1285/1285), done.
remote: Total 1428 (delta 296), reused 852 (delta 6)
Receiving objects: 100% (1428/1428), 561.72 KiB | 189.00 KiB/s, done.
Resolving deltas: 100% (296/296), done.
  1. Change to its directory which is under git management:
$ cd hi_ta
  1. Make sure your snapshot of origin’s (DCS’s) content is current:
$ git fetch --all
  1. Checkout the branch we are working with. For this example we will use my tc-create branch, richmahn-tc-create-1:
$ git checkout richmahn-tc-create-1 

Branch 'richmahn-tc-create-1' set up to track remote branch 'richmahn-tc-create-1' from 'origin'.
Switched to a new branch 'richmahn-tc-create-1'
  1. Merge master into our branch so it has the same content as master:
$ git merge origin/master
Auto-merging translate/figs-apostrophe/01.md
CONFLICT (add/add): Merge conflict in translate/figs-apostrophe/01.md
Auto-merging translate/figs-abstractnouns/title.md
CONFLICT (add/add): Merge conflict in translate/figs-abstractnouns/title.md
Auto-merging translate/figs-abstractnouns/sub-title.md
CONFLICT (add/add): Merge conflict in translate/figs-abstractnouns/sub-title.md
Automatic merge failed; fix conflicts and then commit the result.

Above we see the same 3 files that we saw in the above screen shot in the DCS GUI have conflicts. What we need to do know is edit each one and pick which changes we want to keep or delete. See this document for understanding the conflict notation.

  1. There are multiple ways you can resolve conflicts:

    a. Method 1: edit the file and resolve conflicts line by line,

    b. Method 2: reject ALL our changes and keep ALL master’s changes or

    c. Method 3: keep ALL our changes and reject ALL of master’s changes

    See below for each method

    We used each method on the 3 conflicting files: for 01.md we used method 1 to merge changes in both master and our branch; for title.md we used method 2 to accept master’s changes and reject ours; and for sub-title.md we used method 3 to accept our changes and reject master’s. If you do a git status you should see that only the first two files will be committed as the 3rd we discarded our changes:

$ git status
On branch richmahn-tc-create-1
Your branch is up to date with 'origin/richmahn-tc-create-1'.

All conflicts fixed but you are still merging.
  (use "git commit" to conclude merge)

Changes to be committed:

	modified:   translate/figs-abstractnouns/title.md
	modified:   translate/figs-apostrophe/01.md

Again, you do NOT see sub-title.md here because we kept our changes thus there is no change to the file in our branch. We are now ready to move on to step 8.

  1. Add our changes to the current merge in progress and then continue the merge
    <a name="step-8>
$ git add translate/figs-abstractnouns/title.md translate/figs-apostrophe/01.md
$ git merge --continue

Now you will be prompted in an editor to edit the merge message for this commit. Just save and exit. You’ll get a confirmation such as:

[richmahn-tc-create-1 e10ae64] Merge branch 'master' into richmahn-tc-create-1

Now push your branch back to DCS so we can make a PR without conflicts:

$ git push
Enumerating objects: 16, done.
Counting objects: 100% (16/16), done.
Delta compression using up to 4 threads
Compressing objects: 100% (5/5), done.
Writing objects: 100% (6/6), 626 bytes | 626.00 KiB/s, done.
Total 6 (delta 2), reused 0 (delta 0)
remote: 
remote: Visit the existing pull request:
remote:   https://git.door43.org/MyOrg/hi_ta/pulls/2
remote: 
remote: . Processing 1 references
remote: Processed 1 references in total
To git.door43.org:MyOrg/hi_ta.git
   0c6a0fe..e10ae64  richmahn-tc-create-1 -> richmahn-tc-create-1

On DCS you’ll now see the PR (linked in the push message) without conflicts which you can safely merge into master:

This concludes this tutorial. Below are the methods of resolving conflicts as mentioned above:

Conflict Resolution Methods


Here are detail examples of each method:

Method 1: edit the file and resolve conflicts line by line:


We will use the translate/figs-apostrophe/01.md as an example for doing this. We will use the command line editor vim to do this:

$ vim translate/figs-apostrophe/01.md

I have noted the changes I wanted to keep when I made changes, just so you could understand what needs to be kept and deleted. Example initial content of the 01.md file:

### Description

<<<<<<< HEAD
An apostrophe is a figure of speech in which a speaker turns his attention away from his listeners and speaks to someone or something that he knows cannot hear him. He does this to tell his listeners his message or feelings about that person or thing in a very strong way. (richmahn change that I want)

#### Reason This Is a Translation Issue

Many languages do not use apostrophe, and readers could be confused by it. They may wonder who the speaker is talking to, or think that the speaker is crazy to talk to things or people who cannot hear..... (richmahn change that I don't want. to many periods)

### Examples from the Bible

> MMountains of Gilboa, let there not be dew or rain on you. (2 Samuel 1:21a ULT)

KKing Saul was killed on Mount Gilboa, and David sang a sad song about it. By telling these mountains that he wanted them to have no dew or rain, he showed how sad he was.

> JJerusalem, Jerusalem, who kills the prophets and stones those sent to you. (Luke 13:34a ULT)

JJesus was expressing his feelings for the people of Jerusalem in front of his disciples and a group of Pharisees. By speaking directly to Jerusalem as though its people could hear him, Jesus showed how deeply he cared about them.

> HHe cried against the altar by the word of Yahweh: "**Altar**, **altar**! This is what Yahweh says, ‘See, … on you they will burn human bones.’“ (1 Kings 13:2 ULT)

TThe man of God spoke as if the altar could hear him, but he really wanted the king, who was standing there, to hear him.
=======
AAAAn apostrophe is a figure of speech in which a speaker turns his attention away from his listeners and speaks to someone or something that he knows cannot hear him. He does this to tell his listeners his message or feelings about that person or thing in a very strong way. (other user change that I don't want)

#### Reason This Is a Translation Issue

Many languages do not use apostrophe, and readers could be confused by it. They may wonder who the speaker is talking to, or think that the speaker is crazy to talk to things or people who cannot hear... (other user change that I do want)

### Examples from the Bible

> Mountains of Gilboa, let there not be dew or rain on youu. (2 Samuel 1:21a ULT)

King Saul was killed on Mount Gilboa, and David sang a sad song about it. By telling these mountains that he wanted them to have no dew or rain, he showed how sad he wass.

> Jerusalem, Jerusalem, who kills the prophets and stones those sent to youu. (Luke 13:34a ULT)

Jesus was expressing his feelings for the people of Jerusalem in front of his disciples and a group of Pharisees. By speaking directly to Jerusalem as though its people could hear him, Jesus showed how deeply he cared about them.

> He cried against the altar by the word of Yahweh: "**Altar**, **altar**! This is what Yahweh says, ‘See, … on you they will burn human boness.’“ (1 Kings 13:2 ULT)

The man of God spoke as if the altar could hear him, but he really wanted the king, who was standing there, to hear himm.
>>>>>>> master

### Translation Strategies

If apostrophe would be natural and give the right meaning in your language, consider using it. But if this way of speaking would be confusing to your people, let the speaker continue speaking to the people that are listening to him as he tells **them** his message or feelings about the people or thing that cannot hear him. See the example below.

### Examples of Translation Strategies Applied

> He cried against the altar by the word of Yahweh: "**Altar**, **altar**! This is what Yahweh says, ‘See, … on you they will burn human bones.’“ (1 Kings 13:2 ULT)
>
> > He said this about the altar: “This is what Yahweh says **about this altar.** ‘See, … they will burn people’s bones on **it**.’“
>
> **Mountains of Gilboa**, let there not be dew or rain on **you.** (2 Samuel 1:21a ULT)
>
> > **As for these mountains of Gilboa**, let there not be dew or rain on **them**.

It’s imported to notice that most of the document is repeated, except the first line and the last few lines. That is because all the lines in-between conflict. The first bloock of the duplicated text is from my branch, annotated by <<<<<<< HEAD and then the duplicated text is separated by ``=======` and the bottom block is annotated with “>>>>>> master” meaning that block is from master.

Note: there can be more than one instance of these HEAD/master pairs of blocks, so make sure you address all of them, merging one block into the other and remove the lines that start with “<<<” , “>>>” and “===”.

Making sure we get both changes, you have to go line by line on each block and figure out what changed and what you want to keep, merging both blocks into one manually. My desired final file content is as follows:

### Description

An apostrophe is a figure of speech in which a speaker turns his attention away from his listeners and speaks to someone or something that he knows cannot hear him. He does this to tell his listeners his message or feelings about that person or thing in a very strong way. (richmahn change that I want)

#### Reason This Is a Translation Issue

Many languages do not use apostrophe, and readers could be confused by it. They may wonder who the speaker is talking to, or think that the speaker is crazy to talk to things or people who cannot hear... (other user change that I do want)

### Examples from the Bible

> Mountains of Gilboa, let there not be dew or rain on youu. (2 Samuel 1:21a ULT)

KKing Saul was killed on Mount Gilboa, and David sang a sad song about it. By telling these mountains that he wanted them to have no dew or rain, he showed how sad he wass.

> Jerusalem, Jerusalem, who kills the prophets and stones those sent to you. (Luke 13:34a ULT)

JJesus was expressing his feelings for the people of Jerusalem in front of his disciples and a group of Pharisees. By speaking directly to Jerusalem as though its people could hear him, Jesus showed how deeply he cared about them.

> He cried against the altar by the word of Yahweh: "**Altar**, **altar**! This is what Yahweh says, ‘See, … on you they will burn human boneds.’“ (1 Kings 13:2 ULT)

TThe man of God spoke as if the altar could hear him, but he really wanted the king, who was standing there, to hear himm.

### Translation Strategies

If apostrophe would be natural and give the right meaning in your language, consider using it. But if this way of speaking would be confusing to your people, let the speaker continue speaking to the people that are listening to him as he tells **them** his message or feelings about the people or thing that cannot hear him. See the example below.

### Examples of Translation Strategies Applied

> He cried against the altar by the word of Yahweh: "**Altar**, **altar**! This is what Yahweh says, ‘See, … on you they will burn human bones.’“ (1 Kings 13:2 ULT)
> 
> > He said this about the altar: “This is what Yahweh says **about this altar.** ‘See, … they will burn people’s bones on **it**.’“
> 
> **Mountains of Gilboa**, let there not be dew or rain on **you.** (2 Samuel 1:21a ULT)
> 
> > **As for these mountains of Gilboa**, let there not be dew or rain on **them**.

Method 2: reject ALL our changes and keep ALL master’s changes or


If you know you want what was already done in master, just type this:

$ git checkout --theirs translate/figs-abstractnouns/title.md

This will discard any changes “our” branch has been made for “theirs”.

Method 3: keep ALL our changes and reject ALL of master’s changes


If you know you want all our changes and none of the master changes, just type this:

$ git checkout --ours translate/figs-abstractnouns/sub-title.md

@rich Can we also use this Update Branch button that I see in some circumstances?

@jag3773 I don’t believe you can use that if there are conflicts. It will maybe tell you how to resolve the conflicts locally.

So the update branch will just merge master in to the user’s branch, which can only be done if there are NOT conflicts.

If there are conflicts, Gitea/DCS will only tell you right here, instead of the Update branch and Squash and Merge buttons, which files are conflicting. There is no way to handle it here. I am writing another article on how to resolve with SmartGit: Resolving Conflicts in a PR on DCS with SmartGit