How to organize revisions in hierarchies?

Question

When working with version control, the history generally looks like a flat chain of revisions. There is some rudimentary mechanism of organizing a hierarchy (I mean branches), but it doesn't seem flexible enough. What are common practices (version control agnostic) to organize revisions in multi-level hierarchies and what are version control tool specific gotchas?

I'll provide a trivial real world example from my practice which lead me to this question.

Assume I want to refactor a function/class method. I create a ticket and name it let's say "Refactor method ClassName.method_name()". After studying the code of method_name(), I divide the refactoring process into subtasks. For simplicity, let's consider I need to rename two variables with different meanings in the code, so I need to do it in two distinct atomic steps. I rename a variable, save the changes and commit with message "renamed foo variable in ClassName.method_name()" (because committing early and committing often is good). I repeat for the second variable: "renamed bar variable in ClassName.method_name()".

Now I have one ticket in the issue tracker, named "Refactor method ClassName.method_name()" and two revisions in version control:

• "renamed foo variable in ClassName.method_name()"
• "renamed bar variable in ClassName.method_name()"

Where is the relation between the issue and these two revisions? I'm lost!

My goal is to have a logical hierarchy like this:

• "Refactor method ClassName.method_name()"
  • "renamed foo variable in ClassName.method_name()"
  • "renamed bar variable in ClassName.method_name()"

Needless to say I'm looking for general workflows, which would allow creating multi-level hierarchies like this one. Each item of the hierarchy can be a revision or a ticket, the situation with a ticket being fixed by a chain of consecutive revisions is just a particular case.

This would make sense, I'm a fan of using outliners and organizing data into hierarchies using trees.

How do people do this in version control? There are many version control tools, each have their subtleties, some allow to include third party bug trackers right into the repository, some even have integrated bug tracking (like fossil), so please elaborate on workflows for particular version control tools.

Answer 1

What you want is called feature branches, and is a very common workflow with distributed version control. For your example it would go something like this:

• Create a branch from your trunk named "refactor method."
• Create a branch from your "refactor method" branch named "rename foo."
• Do all your work for renaming foo, committing into the "rename foo" branch as you go along.
• Merge "rename foo" back into "refactor method."
• Create a branch from your "refactor method" branch named "rename bar."
• Do all your work for renaming bar, committing into the "rename bar" branch as you go along.
• Merge "rename bar" back into "refactor method."
• Merge "refactor method" back into your trunk.

Displaying the trunk branch with a graphical tool will show just "refactor method" with a plus sign or something to expand it, sort of like this:

. Clicking the plus sign will reveal "rename foo" and "rename bar." Clicking again will reveal all the individual steps. Also, the work can happen in parallel, people checking in in a different order than they checked out, and you will still get the hierarchical history. In my graphic, you can see that Arnold checked in his bug fix after Amy branched off for her change, but the history still works.