Merge branch 'improve-kata-documentation' of https://github.com/brent…

…-clark-SED-Sw-Mgr/git-katas into add-to-basic-commits-readme

Overview.md

@@ -1,73 +1,55 @@
-# Overview of Git Katas
+# Overview of the Git Kata Exercises
 
+## Setup
 
-## [Bad-commit](bad-commit/README.md)
-Cleaning up a bit.
+1. [configure-git](configure-git/README.md) - If git is not configured, some basic configuration steps
 
-## [basic-commits](basic-commits/README.md)
-Very basic creation of commits.
+## Basic Git Katas in Suggested Order
 
-## [basic-staging](basic-staging/README.md)
-interacting with the stage (index).
+1. [basic-commits](basic-commits/README.md) - Very basic creation of commits.
+1. [basic-staging](basic-staging/README.md) - Interacting with the stage (index).
+1. [basic-branching](basic-branching/README.md) - The first stride into branching.
+1. [ff-merge](ff-merge/README.md) - A tour around the most trivial of merges.
+1. [3-way-merge](3-way-merge/README.md) - A basic merge, involving multiple diverged branches.
+1. [merge-conflict](merge-conflict/README.md) - A basic merge between diverging branches with incompatible (but simple) changesets.
+1. [merge-mergesort](merge-mergesort/README.md) - A merge conflict with actual code.
+1. [rebase-branch](rebase-branch/README.md) - Using rebase as an alternative to merging.
+1. [basic-revert](basic-revert/README.md) - Use revert to revert a change
+1. [reset](reset/README.md) - Reset is a powerful and slightly dangerous command if you do not know what you are doing. Go through the three modes of resetting here.
+1. [basic-cleaning](basic-cleaning/README.md) - Cleaning the workspace.
+1. [amend](amend/README.md) - Amending previous commits.
+1. [reorder-the-history](reorder-the-history/README.md) - We might have created our commits in a suboptimal order, practice to fix that scenario here.
+1. [advanced-rebase-interactive](advanced-rebase-interactive/README.md) - Practice using the interactive rebase commands.
+1. [basic-stashing](basic-stashing/README.md) - The first stride into stashing.
 
-## [basic-branching](basic-branching/README.md)
-The first stride into branching.
+## Katas that solve standard problems
 
-## [basic-cleaning](basic-cleaning/README.md)
-Cleaning the workspace.
+1. [commit-on-wrong-branch](commit-on-wrong-branch/README.md) - If we accidentally put unpushed commits on the wrong branch, how do we effectively _move_ them to another branch before our work on that branch.
 
-## [ignore](ignore/README.md)
-The basics of using the `.gitignore` file.
 
-## [commit-on-wrong-branch](commit-on-wrong-branch/README.md)
-An administrative exercise, how do we _move_ a commit that we accidentally put on the wrong branch.
+## Katas Not Yet Ordered
 
-## [commit-on-wrong-branch-2](commit-on-wrong-branch-2/README.md)
-Another exercise on what to do if you have accidentally committed
-on the wrong branch.
+1. [reverted-merge](reverted-merge/README.md) - A merge has to be reverted, but this causes problems.
+1. [commit-on-wrong-branch-2](commit-on-wrong-branch-2/README.md) - Another exercise on what to do if you have accidentally committed on the wrong branch.
+1. [ignore](ignore/README.md) - The basics of using the `.gitignore` file.
+1. [save-my-commit](save-my-commit/README.md) - Should you accidentally or on purpose delete a commit, go here to try and save it.
+1. [squashing](squashing/README.md) - A lot of small commits is good when you are working locally, but for sharing your code, it might be more beneficial to deliver your code changes in large sets. Go here to experiment with that.
+1. [submodules](submodules/README.md) - Submodules are loathed by many. Run through this exercise to see what the ruckus is all about.
 
-## [ff-merge](ff-merge/README.md)
-A tour around the most trivial of merges.
 
-## [3-way-merge](3-way-merge/README.md)
-A basic merge, involving multiple diverged branches.
+## Katas On Advanced features
 
-## [merge-conflict](merge-conflict/README.md)
-A basic merge between diverging branches with incompatible changesets.
+1. [Bad-commit](bad-commit/README.md) - Using `git bisect` to find a bad commit.
+1. [pre-push](pre-push/README.md) - A quick exercise in using Git hooks.
+1. [Investigation](investigation/README.md) - Discover what is going on in a Git repo, figure out what it looks like under the hood.
+1. [Objects](objects/README.md) - A small exercise into Git internals.
 
-## [merge-mergesort](merge-mergesort/README.md)
-A merge conflict with actual code.
 
-## [reverted-merge](reverted-merge/README.md)
-A merge has to be reverted, but this causes problems.
+## Katas not yet described or put in order
 
-## [rebase-branch](rebase-branch/README.md)
-Using rebase as an alternative to merging.
+1. [bisect](bisect/README.md) - TBD
+1. [detached-head](detached-head/README.md) - TBD
+1. [merge-driver](merge-driver/README.md) - TBD
+1. [rebase-exec](rebase-exec/README.md) - TBD
 
-## [pre-push](pre-push/README.md)
-A quick exercise in using Git hooks.
 
-## [reorder-the-history](reorder-the-history/README.md)
-We might have created our commits in a suboptimal order, practice to fix that scenario here.
-
-## [reset](reset/README.md)
-Reset is a powerful and slightly dangerous command if you do not know what you are doing.
-Go trough the three modes of resetting here.
-
-## [basic-stashing](basic-stashing/README.md)
-The first stride into stashing.
-
-## [save-my-commit](save-my-commit/README.md)
-Should you accidentally or on purpose delete a commit, go here to try and save it.
-
-## [squashing](squashing/README.md)
-A lot of small commits is good when you are working locally, but for sharing your code, it might be more beneficial to deliver your code changes in large sets. Go here to experiment with that.
-
-## [submodules](submodules/README.md)
-Submodules are loathed by many. Run through this exercise to see what the ruckus is all about.
-
-## [Investigation](investigation/README.md)
-Discover what is going on in a Git repo, figure out what it looks like under the hood.
-
-## [Objects](objects/README.md)
-A small exercise into Git internals.

amend/README.md

@@ -9,9 +9,17 @@ Sometimes we just forget something obvious that we want to fix quickly.
 1. Run `. setup.sh` (or `.\setup.ps1` in PowerShell)
 
 ## The task
+
 1. What does `git status` tell us?
-2. What does `git log` tell us?
-3. Stage the addition of bar.txt
-4. Run `git commit --amend`
-5. What happened? What does `git log` tell us?
-6. What happens if you run `git commit --amend` again?
+1. What does `git log` tell us?
+1. Stage the addition of bar.txt
+1. Run `git commit --amend`
+1. What happened? What does `git log` tell us?
+1. What happens if you run `git commit --amend` again?
+
+## Useful commands
+
+- `git add`
+- `git log --oneline --graph`
+- `git commit --amend`
+

bad-commit/README.md

@@ -9,6 +9,22 @@ Find the commit and revert it using bisect.
 
 1. Run `. setup.sh` (or `.\setup.ps1` in PowerShell)
 
+## The task
+
+Use `git bisect` to find the bad commit and then use `git revert` to revert it. When running `git bisect`, you indicate if the "state" is good or bad until it finds commit that made it bad.
+
+1. What does bad commit mean? For this exercise, its when we added the file `badfile`
+1. Start the `git bisect`.
+1. Tell `git bisect` that the current commit is bad.
+1. Checkout at the oldest commit. No `badfile` so it is good. Tell `git bisect` that oldest commit is good.
+1. `git bisect` will then checkout at various commits to find the bad commit. Indicate `git bisect good` or `git bisect bad`. Continue until it tells you the first bad commit. Keep track of it.
+1. `git bisect reset` so we can work on the repository.
+1. We know which commit introduced the bad file, so we fix the problem. What happened in that the bad commit? Use `git diff` to see that it only introduced `badfile`.
+1. That means we can use `git revert` to it
+
+1. Someone else can figure out how to use `git bisect run` since usually a single script won't find the problem.
+
+
 ## Useful commands
 
 - `git bisect start`
@@ -19,3 +35,5 @@ Find the commit and revert it using bisect.
 - `git bisect run <cmd>`
 - `test ! -f badfile` (or `gci . badfile` in PowerShell) to test the existence of a file
 - `test ! -f badfile;echo $?` to output the result of the test to the console
+- `git diff --name-only SHA1 SHA2`
+- `git revert SHA1`

basic-commits/README.md

@@ -1,13 +1,15 @@
 # Git Kata: Basic Commits
-This kata will introduce you to the commands `git add` and `git commit`.
+This kata will introduce you to the commands `git add` and `git commit`. 
+
+This is a very introductory kata. if you have used `git status`, `git log --oneline --graph`, `git add` and `git commit` extensively you should probably skip it.
 
 This is a very introductory kata. if you have used `git status`, `git log --oneline --graph`, `git add` and `git commit` extensively you should probably skip it.
 
 You can look at the bottom of this file, if you have not yet done basic git configuration.
 
 ## Setup:
 
-1. Run `. setup.sh` (or `.\setup.ps1` in PowerShell)
+1. Run `. setup.sh` (or `.\setup.ps1` in PowerShell) and `cd exercise`
 
 ## The task
 

basic-revert/README.md

@@ -8,13 +8,13 @@
 You again live in your own branch, this time we will revert some change on a branch.
 
 1. Create a branch called `reverting`
-2. Checkout the branch
-3. What is the output of `git branch`?
-4. What is the output of `git log --oneline --graph --all`
-5. Use `cat` to see the contents of the greetings
-6. Revert the latest change, so you get the original content in the file
-7. Use `cat` to see the contents of the greetings
-8. Diff the branches
+1. Checkout the branch
+1. What is the output of `git branch`?
+1. What is the output of `git log --oneline --graph --all` and of `git log -p`
+1. Use `cat` to see the contents of the greetings
+1. Revert the latest change, so you get the original content in the file
+1. Use `cat` to see the contents of the greetings
+1. Diff the branches
 
 ## Useful commands
 - `git branch`
@@ -27,4 +27,5 @@ You again live in your own branch, this time we will revert some change on a bra
 - `git commit -m`
 - `git revert <sha1>`
 - `git diff <branchA> <branchB>`
+- `git log -p`
 - `git log --oneline --graph --all`

basic-staging/README.md

@@ -1,6 +1,6 @@
 # Git Kata: Basic Staging
 
-This kata will examine the staging area of git.
+This kata will examine the staging area of git. This is another very introductory kata, although it introduces `git diff` and `git reset` and if you are not familiar with these commands probably should work through it.
 
 In git we are working with three different areas:
 * The working directory where you are making your changes
@@ -14,7 +14,7 @@ We will also work with `git reset` to reset the staged changes of a file, and `g
 
 ## Setup:
 
-1. Run `. setup.sh` (or `.\setup.ps1` in PowerShell)
+1. Run `. setup.sh` (or `.\setup.ps1` in PowerShell) and `cd exercise`
 
 ## The task
 

commit-on-wrong-branch/README.md

@@ -39,3 +39,15 @@ But you want it to look like this:
 Git ahead!
 
 Note: since the B in the current and in the target structure don't have the same parent they can't be literally the same commit.
+
+## The task
+
+1. Use `git log --oneline --graph --all` to view the branches and their commits.
+1. Copy C onto master before B by rebasing quickfix on master.
+1. Delete the quickfix branch
+
+
+## Useful commands
+- `git log --oneline --graph --all`
+- `git rebase <branch-name>`
+

investigation/README.md

@@ -17,3 +17,9 @@ Objects are stored in `<repository>/.git/objects` in subfolders matching the fir
 1. Using `git ls-tree` and `git cat-file`, draw the entire Git data structure.
 	- What tree and blob objects do you have and what do they point at?
 	- What commits point inside this graph and where?
+
+**Its not clear what the point of this exercise is.**
+
+## Useful commands
+- `git ls-tree -r -t SHA1`
+

merge-conflict/README.md

@@ -6,11 +6,20 @@
 
 ## The task
 
-In this kata git cannot figure how to merge the content added on `merge-conflict-branch1` with the content on `master`.
+In this kata, git cannot figure how to merge the content added on `merge-conflict-branch1` with the content on `master`.
 
 Both changes need to be in master when you're done.
 
+1. Use `git merge` to bring the changes from `merge-conflict-branch1` on to `master`
+1. What does `git status` now report.
+1. Fix the conflict with your favorite editor
+1. Follow the instructions in `git status` to complete the merge
+1. What does `git log --oneline --graph --all`
+
+
 ## Relevant commands
 - `git merge`
+- `git status`
 - `git add`
 - `git commit`
+- `git log --oneline --graph --all`

merge-mergesort/README.md

@@ -14,7 +14,19 @@ The task is to look at the merge conflict, and solve it by editing the file acco
 ## The task
 
 1. Run `git branch` to see the two branches present
-2. `git merge Mergesort-impl`
-3. Solve the merge conflict :)
-
+1. Run `git log --oneline --graph --all` to see the commits on all the branches
+1. Merge from `Mergesort-Impl`
+1. Either:
+   1. Solve the merge conflict with your favorite editor and finish the merge (`git status` will tell you what to do), **or**
+   1. Use `git mergetool --tool=emerge` (for emacs fans) or `git mergetool --tool=vimdiff` (for vim fans) and finish the merge (`git status` will tell you what to do)
+
+## Relevant commands
+- `git branch`
+- `git log --oneline --graph --all`
+- `git merge`
+- `git status`
+- `git mergetool --tool=emerge` 
+- `git mergetool --tool=vimdiff` 
+- `git add`
+- `git commit`
 

reorder-the-history/README.md

@@ -10,9 +10,15 @@ You should fix this such that our `git log` looks great!
 
 ## Task
 
-1. Reorder the history such that it actually makes sense
+Reorder the history such that it actually makes sense (the order the files are added matches their number).
+
+1. Use `git log --oneline --graph` to view the commits
+1. Try `git reflog` to also view the commits. `git reflog show` is an alias for `git log -g --abbrev-commit --pretty=oneline`
+1. Use `git rebase -i <after-this-commit>` to reorder the commits. The commments in the file you edit explain the commands you are editing.
+1. Use `git log --oneline --graph` to view the result
 
 ### useful commands
 
-- `git rebase -i`
+- `git rebase -i <after-this-commit>`
+- `git log --oneline --graph`
 - `git reflog`

reset/README.md

@@ -9,12 +9,21 @@ We use reset to unstage change, but we can also do many more different things.
 
 ## Task
 1. How does your working directory look like?
-2. What does your log look like?
-3. Try to run `git reset --soft HEAD~1`
-4. What happens to your working directory, your log and your stage?
-5. Run `git reset --mixed HEAD~1`
-6. What happens to your working directory, your log and your stage?
-7. Run `git reset --hard HEAD~1`
-8. What happens to your working directory, your log and your stage?
-9. Now try to use `git revert HEAD~1`
-10. What happens to your working directory, your log and your stage?
+1. What does your log look like?
+1. What does your reflog look like?
+1. Try to run `git reset --soft HEAD~1`
+1. What happens to your working directory, your log and your stage? Use `git status`, `git log --oneline`, `git reflog`
+1. Run `git reset --mixed HEAD~1`
+1. What happens to your working directory, your log and your stage?
+1. Run `git reset --hard HEAD~1`
+1. What happens to your working directory, your log and your stage?
+1. Now try to use `git revert HEAD~1`
+1. What happens to your working directory, your log and your stage?
+
+## Further explanation
+
+The reset command overwrites the HEAD (Last commit snapshot, next parent), the Index and the Working Directory in a specific order, stopping when you tell it to:
+1. Move the branch HEAD points to (stop here if --soft)
+1. Make the index look like HEAD (stop here unless --hard)
+1. Make the working directory look like the index
+