README.md

   1 # git-rehi, history editor
   2
   3 Takes a history and reruns it, optionally with modifications.
   4
   5 Done to some usable state. See _Usage_ section later for reference.
   6 Bug reports and wishes tracked here: https://github.com/max630/git-rehi
   7
   8 **NOTE**: Older perl version is [here](https://github.com/max630/git-rehi/tree/maint_0.5).
   9
  10 **SAFETY NOTES**: Note that it is an experimental software. You'd better have a
  11 backup if you run it at a valuable repository, for example it should be cloned
  12 somewhere. I also usually have some temporary reference to the older head and
  13 inspect the result in gitk or otherwise before removing it. And never use
  14 automatic gc (this script does not call it directly, but some of used commands
  15 may trigger it if it is enabled in the config).
  16
  17 ## Motivation
  18
  19 `git-rebase` is a wornderful tool, but it has a list of disadvantages:
  20
  21 * Terribly slow at Windows. I guess it is because it is written in Bash.
  22 * Very poor support for merges. They can be created with exec during interactive rebase,
  23   but when there are already merges, you don't get them back in the todo list.
  24 * Inconvenient UI for reword. User first need to specify the todo list, then
  25   gets into sequence of resolving conflict, and at some point is finally able
  26   to write the comment. Would be much better to do that just during editing
  27   the todo list.
  28
  29 ## Features
  30
  31 List of features
  32
  33 * Written in high-level language, with data structures and string manipulation
  34   without calling external programs.
  35 * Should work on Windows with msysgit only, without installing additoinal software.
  36 * As few git calls as possible.
  37 * Extended language for the todo list.
  38 * Analysis before editing the todo list, selecting only the interesting path
  39   from the history to be changed.
  40
  41 ## Installation
  42
  43 Recommended way:
  44
  45 * install [stack](https://docs.haskellstack.org/en/stable/README/#how-to-install)
  46 * run in the source tree: `stack build`
  47 * last lines of output is something like:
  48
  49     Installing executable(s) in
  50     C:\src\git-rehi\.stack-work\install\i386-linux\lts-3.17\7.10.2\bin
  51
  52 Copy it to a directory in your `PATH` and it is ready to use.
  53
  54 ## Usage
  55
  56 Run the script inside of a git repository. If it is in PATH, git will run it
  57 for you if you use `git rehi`.
  58
  59 `git rehi [options] <dest> [[<source_from>]..[<through1>..<through2>]..[<source_to>]] [<target>]`
  60
  61 Calculates a path (a) from `<source_from>` to `<source_to>`, and apply
  62 it to repository, starting from `<dest>`. In the end, `<target>` branch is
  63 reset to the top of the resulting commit sequence and checked out.
  64
  65 Optionally between `<source_from>` and `<source_to>` can be one or more
  66 `<through>` revisions. Then the source path is adjusted so that it contains all
  67 of these revisions.
  68
  69 If `<source_from>` is omitted, the latest common ancestor of `<dest>` and
  70 `<source_to>` is used instead.  If `<source_to>` is omitted, `<target>` is used
  71 instead.  If `<target>` is omitted, the currently checked-out branch is used.
  72 If the whole source argument `<from>.. ..<to>` is omitted, it is equivalent to
  73 specification "`..`".
  74
  75 `git rehi --continue`
  76
  77 Retry failed step after resolution. For some types of step this is not supported.
  78 Then user have to manually apply the step and use `git rehi --skip` to continue.
  79
  80 `git rehi --abort`
  81
  82 Aborts whole reapply. The originally checked-out branch is checked out back.
  83
  84 `git rehi --skip`
  85
  86 Reset all uncommitted changes and continue reapplying starting with the next step in todo list.
  87
  88 `git rehi --current`
  89
  90 If there is a reapplying in progress, shows current step.
  91
  92 (a): the default path is some "optimal" which is not strictly specified and
  93 subject to change. At some point it was the shortest. Now general rule is to
  94 follow first parent but I might want to tune how it resolves ambiguous cases.
  95
  96 ### Options
  97
  98 `--interactive`
  99
 100 Allows user to edit step list before starting applying them.
 101
 102 ### Steps
 103
 104 Types of step, which `git-rehi` recognizes and which can be used in todo list.
 105
 106 `pick <ahash> [<subject>]`
 107
 108 Apply the non-merge change at specified hash `ahash`, repeating it comment and
 109 author. `subject` is ignored. Can be abbreviated to `p`.
 110
 111 `fixup <ahash> [<subject>]`
 112
 113 Apply the non-merge change at specified hash `ahash` and amend the latest
 114 commit which is currently in HEAD. No change to message. `subject` is ignored.
 115 Can be abbreviated to `f`.
 116
 117 `comment`
 118
 119 Change the message of the latest commit. Following lines are the message contents.
 120 A line containing single "." marks the end of message.
 121
 122 `merge [--ours] -c <ahash> <ahash_1>,<ahash_2>,... [<subject>]`
 123
 124 Merge latest commit with others. Parents of the resulting commits will be
 125 `ahash_1`, `ahash_2` and so on.  Their order exactly the same as specified in
 126 the command. Exactly one of the `ahash_N` should be literal "`HEAD`" (without
 127 quotes). If `--ours` is specified, merge will be performed with strategy `ours`
 128 (that is, is will copy the `ahash_1`, just marking others as merged and
 129 ignoring their contents).
 130
 131 Message for commit is taken from the `ahash` commit. `subject` is ignored.
 132
 133 `edit <ahash> [<subject>]`
 134
 135 Like `pick`, but stops after that, allowing user to make some manual changes.
 136 Can be abbreviated to `e`.
 137
 138 `reset <ahash>`
 139
 140 Reset to the `ahash` commit and continue to apply following steps on top of it.
 141
 142 `: <mark>`
 143
 144 Remember current HEAD as a `mark`. Anywhere in the todo steps `ahash` can be
 145 of form `@<mark>`. If it has been remembered before, the hash of the mark
 146 will be used.
 147
 148 `exec <command>`
 149
 150 Executes a shell command. Can be abbreviated to `x`.
 151
 152 ## Types of merge
 153
 154 * merge which contains only one parent from changes sequence, and all others
 155   already exist and are untouched by the reapplying. I call it "external merge".
 156   External merges are supported: detected and handled when specified in todo.
 157 * merge which contains two or more parents from changes sequence. That is
 158   "internal merge". There is an experimental support for such merges, with use
 159   of `reset` and `:` steps.