TODO file as a support while working on feature branch

README.md

Work with TODO file

This gist presents a methodology of working on a task on feature branch using a TODO file as a support.

How?

Here is a possible scenario:

1. Turn on verbose commits option: git config --local commit.verbose true. It's really awesome!
2. Take a task from your project management tool.
3. cd to repo.
4. Checkout to a main branch on the repo: git checkout master.
5. Pull the most recent changes from origin: git pull origin master.
6. Create a feature branch: git checkout -B my-awesome-feature.
7. Create a text TODO file. It can be any text file, but the tasks has to start with four characters [ ] - preferably a markdown or xit file. Ideally the task you've picked should be supported with acceptance criteria - you can copy them here to keep track of what is expected to be done. Don't hesitate to add anything that you think of to make the task complete.
8. Add a path of a TODO file to your local git config: git config --local todo.file <file_path>.
9. Work on a branch. Commit frequently. Leave lengthy documentation of the changes you commit (even if it's only a hack/partial commit/work in progress/etc.). It's very usefull to keep the history changes and the trace of reasoning in commits to present full documentation after you've done a task. It is highly recommended to use fixup commits when you make changes to already existing part of your implementation. After all, the simple rebase will make a branch clean, readable, well structured and documented.
10. Any git commit command that opens up an editor, allowing to edit a commit message, will show you as well your todo list from a file. The todo list can be updated in place during editing the commit message. The todo list will not be added to your commit message, unless you copy the parts of that todo list in the commit message section of the COMMIT_EDITMSG.
11. You can either keep the todo file in repo, commiting it during the process or you can exclude it by adding it's file path to .git/info/exclude.
12. After a commit message is save and a commit being created, the script will check whether the list is fully completed and suggests you some actions afterwards. Read them carefully.

Why?

This methodology will keep you focused on items you have defined or operate on during the process of task accomplishment.

The main goal of it is to establish a constant looking at, editing and verifying the todo list. In the result it will force you to keep track of what is to be done.

commit-msg

#!/usr/bin/env bash

sed -n '/# -\+ >8 -\+/,/# -\+ 8< -\+/{/# -\+ >8 -\+/!{/# -\+ 8< -\+/!p;};}' \
    "$1" > "$(git config todo.file)"

post-commit

#!/usr/bin/env bash

todo_file=$(git config todo.file)
export todo_file

current_branch=$(git branch --show-current)
export current_branch

main_branch=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
export main_branch

current_branch_origin=$(git merge-base "$main_branch" "$current_branch")
export current_branch_origin

commits_count=$(git rev-list "$current_branch_origin".. --count)
export commits_count

if [ -z "$todo_file" ]; then
  echo "Todo file not set up. If you have a todo file, set it up with:"
  echo "  git config --local todo.file <file_name>"
else
  if [ -f "$todo_file" ]; then
    unresolved=$(sed -n '/\[[ \?]\] .*/p' "$todo_file" | wc -l)
    export unresolved

    echo "Inspecting todo file '$todo_file'…"
    if [ "$unresolved" -eq 0 ]; then
      echo "  …you are done with your todo list!"
      if [ "$unresolved" -eq 1 ]; then
        echo "  There is one delivery commit."
      else
        echo "  There are $commits_count delivery commits."
      fi
      echo "  Now you can clean the history up:"
      echo "    git rebase -i $current_branch_origin"
      echo "  Before pushing, remember to remove the '$todo_file' file from repo:"
      echo "    git filter-branch --tree-filter 'rm -f $todo_file' $current_branch"
    elif [ "$unresolved" -eq 1 ]; then
      echo "  …one item to go!"
    else
      echo "  …$unresolved unresolved issues left."
    fi
  else
    echo "Todo file '$todo_file' does not exist."
  fi
fi

prepare-commit-msg

#!/usr/bin/env bash

sed -e "/# -\\+ >8 -\\+/r$(git config todo.file)" \
    -e '/# -\+ >8 -\+/a# ------------------------ 8< ------------------------' \
    -i \
    "$1"