Git Workflow that uses only rebase to ensure chronological commits.

no_merge_flow.md

Rebase Flow

This workflow is based on GitHub Flow.

The main goal is to simplify the workflow by applying a rigid structure to how new material is added to the repo, which avoids complicated git merges.

Rebase Flow Commandments

1. Never commit any changes to the local working master branch. Your local working master branch should never get ahead of the master branch on Github. Only commit changes to a working branch.

2. Never call git push from the master branch. This is related to the first sin above.

3. You can call git push --force from your working branch. This happens often, usually when you "rebase from master" or if you ever consolidate the commits within your branch.

Initial Setup - Clone the repo

> git clone https://<url>/project/<repo>
> cd <repo>

Steps to Add New Content

1. Return to master

Before you start any new branch, you should pull down the latest changes from the repo

First, switch your local working copy to the master branch

> git checkout master

If you are working in another branch and you have uncommitted changes, the command above will fail. You should either commit your changes to your branch (which is what I usually do with a commit message of "wip", which stands for "work in progress"), or use "git stash" to stash the changes.

For example, if you've edited the myfile.py and my_other_file.py files, to commit the changes in your local branch

> git add myfile.py my_other_file.py
> git commit -m "work in progress"

To stash all of your changes

> git stash

Later, once you've returned to your working branch, if you want to apply those changes, you can git stash (pop | apply). See the docs. However, sometimes I forget my stash, which is why I usually commit.

Once you've either committed or stashed your changes, the git checkout master should work without fail.

2. Pull from Github to update master

Get any changes from Github master.

First, verify that you really are on the master branch.

> git branch

This should print out all of the local branches with a star (*) next to master, indicating you are in the master branch.

> git pull origin

3. Add Your Work

3a.Create New Branch

You will create a new branch for your particular changes to the repository.

> git checkout -b my_new_branch

Use a descriptive branch name, such as initial_additions_to_conclusions_section, and not something generic like my_new_branch.

3b. Make changes to the file

Now you can add changes to the source files in the repository. Ensure that your code builds/runs properly and passes any tests that you have.

Review the files that you've made changes to

> git status

3c. Commit your changes to your local working branch

> git add fileone.py filetwo.py filethree.py
> git commit  

You are encouraged to make multiple small commits in your local branch. This helps you to recover if you make a mistake and want to go back to a previous commit. Every once in a while you may need to rebase the commits in your branch in order to fashion the commits into logical chunks of code.

3d. Push Your changes to Github in your branch

You will now upload your changes to Github in a separate branch

> git push -u origin my_new_branch

You can make as many commits and push to your my_new_branch as you wish while you work.

4. Submit Pull Request

Once you've completed your work

• go to https:///project/
• find the "Pull Requests" tab
• click on New Pull Request
• choose the master branch on the left ("base") and my_new_branch for the right ("compare").
• click 'Create Pull Request' green button
• add Title
• add description of what you're adding
• review the comparison of changes on the webpage below to make sure it looks right.
• click 'Create Pull Request' green button
• ask for somebody to review your work

5. Dealing with Reviews

A reviewer can comment on the Github webpage where they think text should be changed. Additionally, we can just send emails and chat on Slack about changes. Whatever is easiest.

After discussing with a reviewer, make any changes to your work, in your working branch, just as before. Here you may need to rebase in order for your commits to follow logically (the commits should be readable by a future developer). Follow the steps above to git add, git commit, and ultimately to git push -u origin my_new_branch.

6. Dealing with an updated Master

The most complicated part of this process will be if the master branch is updated by another pull request after you created your my_new_branch.

Once you are complete with your changes, you should "rebase from master".

This is how you rebase from master.

> git checkout master
> git pull
> git checkout my_new_branch
> git rebase master

You'll get one of three responses: Everything up to date, Successful rebase, or conflicts.

Hopefully there aren't any conflicts. And there shouldn't be too many if team members are working on separate parts of the source code.

But, if there are conflicts, the command line should tell you what to do to fix those conflicts. You'll need to go in and merge those by hand. Then you'll have to do something like git commit --amend and then git rebase --continue. If you are unsure about what you're doing, you can git rebase --abort and everything will return to the state before you called git rebase master.

Now, if you've successfully rebased from master, you'll need to "force push" your branch back to Github.

> git checkout my_new_branch #just to be sure you're not in master!
> git push -f 

7. Final Review

Have the reviewer make a comment on the Github page to "+1" the pull request.

8. Merge

Now safe to merge.