Git Gremlin: Pull Request Fake Out (to Clean Up A Messy Pull Request)
Tags: git, github
Published: 2020-12-29 18:00:00

Git is a free and open-source distributed version control system, designed to help developers handle small to large code changes with efficiency. But, _with great ease comes great opportunity for screw-ups_. It is quite easy (especially for beginners) to make a small mistake with Git that can have a seemingly catastrophic effect on overall work. Some Git mistakes are more intimidating and difficult to correct than others, but fear not! There is no need to panic — you can roll back a Git disaster with some help.  For the _infinite_ number of ways one can make an error with Git, **Git Gremlin** provides useful tips for what to do when things don't go as planned.
_____________________________________________________________

* [User Story](#user-story)
* [Scenario](#scenario)
* [Issue](#what-is-the-issue) 
* [Resolution](#how-to-resolve-the-issue)
* [Prerequisites](#prerequisites)
* [Procedure](#procedure)

_____________________________________________________________
#### User Story
_As a developer who has created a flawed pull request, I want to seamlessly change the content of a pull request and augment its history, so that my initial mistake is not visible in the commit history_
_____________________________________________________________

### Scenario
You are a new contributor to a repository and have just submitted a pull request (PR) that must be reviewed and approved by a maintainer to be merged. You created the initial pull request, it was reviewed, comments were left, and you added some additional commits. 

For whatever reason (maybe you accidentally pulled in additional commits during a rebase, or found an error in a commit you pushed to the PR) you want to completely change the content of the pull request, but do not want to close the pull request. You want to keep the history of the comments the maintainer left when reviewing your initial pull request, but also want to essentially rewrite the commit history and add entirely brand new content to the same pull request.


### What is the Issue? 

How do you completely change the history and content of a single pull request, without closing it? Let's look at the example below.

If the pull request looks like the following image:
![Inital pull request with multiple commits and errors](https://dev-to-uploads.s3.amazonaws.com/i/dr1x720fo84by9lxk18z.jpg)

How can you clean up the pull request, so it looks more like this?
![Same pull request with a single new commit](https://dev-to-uploads.s3.amazonaws.com/i/4kjdls63lojumis9vh8f.jpg)
  ___________________________________________________________

### How to Resolve the Issue?

There are actually a number of ways you can approach this issue, but the following solution will employ a branch renaming strategy to solve the problem. 

For the solution, you are essentially faking the branching strategy. You will rename the original branch the pull request is on, create a new branch to add content to, and then rename the new branch with the original branch name. A bit confusing, but it's clarified in the steps below. 

#### Prerequisites

To get started you should have the following:
* A pull request you want to change/work on.
* You should know which branch the pull request is being pushed into.
* You will need to use the terminal and your text editor. This is solution does not use the GitHub UI.

For the procedure, the following is assumed:
* You have forked and cloned the repository you plan to work on. 
* The remote branch is named `origin`.
* The name of the branch the pull request is on is `docs_restructure`
* The pull request is being pushed to the `main` branch (default branch). 


#### Procedure

To start, check which branch you are on by using `git status`. You should see an output similar to the following after you enter the command:

```
$ git status
On branch docs_restructure
```

Rename the original (current) branch
```
$ git branch -M <ORIGINAL_BRANCH_NAME> <NEW_NAME>
```

For example, you should enter a command similar to the 
following, if you're using `docs_restructure` as the original branch name:

```
$ git branch -M docs_restructure docs_change
```

After the branch has been renamed, you can verify the change has been applied by using `git status`.

```
$ git status
```

You should see an output similar to the following:

```
On branch docs_change
```

Switch to the default branch.  

> In most repositories, this branch is labeled either `master`, `main`, `developer`, or `development`. In any case, it should be the branch that the pull request is being pushed to. 

```
$ git checkout main
```

You should see an output similar to the following:

```
Switched to branch 'main'
Your branch is up to date with 'origin/main'.
```

Now, create an entirely new branch. This new branch is where you can add the content you want to appear in the pull request. 

```
$ git checkout -b <NEW_BRANCH>

Switched to a new branch 'improvement_branch'
```

Rename the new branch, so it has the original name of the branch the initial pull request was on.

```
$ git branch -M <NEW_BRANCH> <ORIGINAL_BRANCH_NAME>
```

For example, you can use the following command:

```
git branch -M improvement_branch docs_restructure
```

__The branch is now named `docs_restructure` - the same as what you started with!__

In the text editor of your choice, make the changes that you would like to see in the pull request and save the content. 

Add the new content to the branch you are currently on.

```
$ git add .
```
Commit the changes. Be sure to leave a commit message that reflects the changes made. 

```
$ git commit -m "restructure docs"
```

Push the changes to the branch. 

```
$ git push <REMOTE_NAME> <ORIGINAL_BRANCH_NAME> --force
```

Following the examples used in this post, the command will look similar to the following:

``` 
$ git push origin docs_restructure --force
```
____________________________________________________________

That's it! If you'd like to dive deeper, please check out more of the _Git Gremlin_ posts. Also, the following resources are helpful for getting more comfortable with Git:

* [Git-SCM](https://git-scm.com/) - Git reference documentation

* [Git Training](https://training.github.com/) - Official Git cheat sheets 

* [Visual Git](https://git-school.github.io/visualizing-git) - A tool for exploring Git visually.

* [Git Game](https://github.com/jlord/git-it-electron) - A desktop application that helps you learn Git through fun challenges.

Thank you for checking out this post, and please _git_ going!