Make copies of the docs and schema folders

The plan is to keep the original docs and schema folders unchanged for the
duration of a release; we'll only continuously update the -master copies. Right
before a new release we will copy them over.

Author: stefanhaller

docs-master/Config.md

@@ -0,0 +1,116 @@
+# Custom Pagers
+
+Lazygit supports custom pagers, [configured](/docs/Config.md) in the config.yml file (which can be opened by pressing `e` in the Status panel).
+
+Support does not extend to Windows users, because we're making use of a package which doesn't have Windows support. However, see [below](#emulating-custom-pagers-on-windows) for a workaround.
+
+Multiple pagers are supported; you can cycle through them with the `|` key. This can be useful if you usually prefer a particular pager, but want to use a different one for certain kinds of diffs.
+
+Pagers are configured with the `pagers` array in the git section; here's an example for a multi-pager setup:
+
+```yaml
+git:
+  pagers:
+    - pager: delta --dark --paging=never
+    - pager: ydiff -p cat -s --wrap --width={{columnWidth}}
+      colorArg: never
+    - externalDiffCommand: difft --color=always
+```
+
+The `colorArg` key is for whether you want the `--color=always` arg in your `git diff` command. Some pagers want it set to `always`, others want it set to `never`. The default is `always`, since that's what most pagers need.
+
+## Delta:
+
+```yaml
+git:
+  pagers:
+    - pager: delta --dark --paging=never
+```
+
+![](https://i.imgur.com/QJpQkF3.png)
+
+A cool feature of delta is --hyperlinks, which renders clickable links for the line numbers in the left margin, and lazygit supports these. To use them, set the `pager:` config to `delta --dark --paging=never --line-numbers --hyperlinks --hyperlinks-file-link-format="lazygit-edit://{path}:{line}"`; this allows you to click on an underlined line number in the diff to jump right to that same line in your editor.
+
+## Diff-so-fancy
+
+```yaml
+git:
+  pagers:
+    - pager: diff-so-fancy
+```
+
+![](https://i.imgur.com/rjH1TpT.png)
+
+## ydiff
+
+```yaml
+gui:
+  sidePanelWidth: 0.2 # gives you more space to show things side-by-side
+git:
+  pagers:
+    - colorArg: never
+      pager: ydiff -p cat -s --wrap --width={{columnWidth}}
+```
+
+![](https://i.imgur.com/vaa8z0H.png)
+
+Be careful with this one, I think the homebrew and pip versions are behind master. I needed to directly download the ydiff script to get the no-pager functionality working.
+
+## Using external diff commands
+
+Some diff tools can't work as a simple pager like the ones above do, because they need access to the entire diff, so just post-processing git's diff is not enough for them. The most notable example is probably [difftastic](https://difftastic.wilfred.me.uk).
+
+These can be used in lazygit by using the `externalDiffCommand` config; in the case of difftastic, that could be
+
+```yaml
+git:
+  pagers:
+    - externalDiffCommand: difft --color=always
+```
+
+The `colorArg` and `pager` options are not used in this case.
+
+You can add whatever extra arguments you prefer for your difftool; for instance
+
+```yaml
+git:
+  pagers:
+    - externalDiffCommand: difft --color=always --display=inline --syntax-highlight=off
+```
+
+Instead of setting this command in lazygit's `externalDiffCommand` config, you can also tell lazygit to use the external diff command that is configured in git itself (`diff.external`), by using
+
+```yaml
+git:
+  pagers:
+    - useExternalDiffGitConfig: true
+```
+
+This can be useful if you also want to use it for diffs on the command line, and it also has the advantage that you can configure it per file type in `.gitattributes`; see https://git-scm.com/docs/gitattributes#_defining_an_external_diff_driver.
+
+## Emulating custom pagers on Windows
+
+There is a trick to emulate custom pagers on Windows using a Powershell script configured as an external diff command. It's not perfect, but certainly better than nothing. To do this, save the following script as `lazygit-pager.ps1` at a convenient place on your disk:
+
+```pwsh
+#!/usr/bin/env pwsh
+
+$old = $args[1].Replace('\', '/')
+$new = $args[4].Replace('\', '/')
+$path = $args[0]
+git diff --no-index --no-ext-diff $old $new
+  | %{ $_.Replace($old, $path).Replace($new, $path) }
+  | delta --width=$env:LAZYGIT_COLUMNS
+```
+
+Use the pager of your choice with the arguments you like in the last line of the script. Personally I wouldn't want to use lazygit anymore without delta's `--hyperlinks --hyperlinks-file-link-format="lazygit-edit://{path}:{line}"` args, see [above](#delta).
+
+In your lazygit config, use
+
+```yml
+git:
+  pagers:
+    - externalDiffCommand: "C:/wherever/lazygit-pager.ps1"
+```
+
+The main limitation of this approach compared to a "real" pager is that renames are not displayed correctly; they are shown as if they were modifications of the old file. (This affects only the hunk headers; the diff itself is always correct.)

docs-master/Custom_Command_Keybindings.md

@@ -0,0 +1,65 @@
+# Fixup Commits
+
+## Background
+
+There's this common scenario that you have a PR in review, the reviewer is
+requesting some changes, and you make those changes and would normally simply
+squash them into the original commit that they came from. If you do that,
+however, there's no way for the reviewer to see what you changed. You could just
+make a separate commit with those changes at the end of the branch, but this is
+not ideal because it results in a git history that is not very clean.
+
+To help with this, git has a concept of fixup commits: you do make a separate
+commit, but the subject of this commit is the string "fixup! " followed by the
+original commit subject. This both tells the reviewer what's going on (you are
+making a change that you later will squash into the designated commit), and it
+provides an easy way to actually perform this squash operation when you are
+ready to do that (before merging).
+
+## Creating fixup commits
+
+You could of course create fixup commits manually by typing in the commit
+message with the prefix yourself. But lazygit has an easier way to do that:
+in the Commits view, select the commit that you want to create a fixup for, and
+press shift-F (for "Create fixup commit for this commit"). This automatically
+creates a commit with the appropriate subject line.
+
+Don't confuse this with the lowercase "f" command ("Fixup commit"); that one
+squashes the selected commit into its parent, this is not what we want here.
+
+## Creating amend commits
+
+There's a special type of fixup commit that uses "amend!" instead of "fixup!" in
+the commit message subject; in addition to fixing up the original commit with
+changes it allows you to also (or only) change the commit message of the
+original commit. The menu that appears when pressing shift-F has options for
+both of these; they bring up a commit message panel similar to when you reword a
+commit, but then create the "amend!" commit containing the new message. Note
+that in that panel you only type the new message as you want it to be
+eventually; lazygit then takes care of formatting the "amend!" commit
+appropriately for you (with the subject of your new message moving into the body
+of the "amend!" commit).
+
+## Squashing fixup commits
+
+When you're ready to merge the branch and want to squash all these fixup commits
+that you created, that's very easy to do: select the first commit of your branch
+and hit shift-S (for "Squash all 'fixup!' commits above selected commit
+(autosquash)"). Boom, done.
+
+## Finding the commit to create a fixup for
+
+When you are making changes to code that you changed earlier in a long branch,
+it can be tedious to find the commit to squash it into. Lazygit has a command to
+help you with this, too: in the Files view, press ctrl-f to select the right
+base commit in the Commits view automatically. From there, you can either press
+shift-F to create a fixup commit for it, or shift-A to amend your changes into
+the commit if you haven't published your branch yet.
+
+If you have many modifications in your working copy, it is a good idea to stage
+related changes that are meant to go into the same fixup commit; if no changes
+are staged, ctrl-f works on all unstaged modifications, and then it might show
+an error if it finds multiple different base commits. If you are interested in
+what the command does to do its magic, and how you can help it work better, you
+may want to read the [design document](dev/Find_Base_Commit_For_Fixup_Design.md)
+that describes this.

docs-master/Custom_Pagers.md

@@ -0,0 +1,11 @@
+# Documentation Overview
+
+* [Configuration](./Config.md).
+* [Custom Commands](./Custom_Command_Keybindings.md)
+* [Custom Pagers](./Custom_Pagers.md)
+* [Dev docs](./dev)
+* [Keybindings](./keybindings)
+* [Undo/Redo](./Undoing.md)
+* [Range Select](./Range_Select.md)
+* [Searching/Filtering](./Searching.md)
+* [Stacked Branches](./Stacked_Branches.md)

docs-master/Fixup_Commits.md

@@ -0,0 +1,14 @@
+# Range Select
+
+Some actions can be performed on a range of contiguous items. For example:
+* staging multiple files at once
+* squashing multiple commits at once
+* copying (for cherry-pick) multiple commits at once
+
+There are two ways to select a range of items:
+1. Sticky range select: Press 'v' to toggle range select, then expand the selection using the up/down arrow key. To reset the selection, press 'v' again.
+2. Non-sticky range select: Press shift+up or shift+down to expand the selection. To reset the selection, press up/down without shift.
+
+The sticky option will be more familiar to vim users, and the second option will feel more natural to users who aren't used to doing things in a modal way.
+
+In order to perform an action on a range of items, simply press the normal key for that action. If the action only works on individual items, it will raise an error. This is a new feature and the plan is to incrementally support range select for more and more actions. If there is an action you would like to support range select which currently does not, please raise an issue in the repo.

docs-master/README.md

@@ -0,0 +1,21 @@
+# Searching/Filtering
+
+## View searching/filtering
+
+Depending on the currently focused view, hitting '/' will bring up a filter or search prompt. When filtering, the contents of the view will be filtered down to only those lines which match the query string. When searching, the contents of the view are not filtered, but matching lines are highlighted and you can iterate through matches with `n`/`N`.
+
+We intend to support filtering for the files view soon, but at the moment it uses searching. We intend to continue using search for the commits view because you typically care about the commits that come before/after a matching commit.
+
+If you would like both filtering and searching to be enabled on a given view, please raise an issue for this.
+
+## Filtering files by status
+
+You can filter the files view to only show staged/unstaged files by pressing `<c-b>` in the files view.
+
+## Filtering commits by file path
+
+You can filter the commits view to only show commits which contain changes to a given file path.
+
+You can do this in a couple of ways:
+1) Start lazygit with the -f flag e.g. `lazygit -f my/path`
+2) From within lazygit, press `<c-s>` and then enter the path of the file you want to filter by

docs-master/Range_Select.md

@@ -0,0 +1,18 @@
+# Working with stacked branches
+
+When working on a large branch it can often be useful to break it down into
+smaller pieces, and it can help to create separate branches for each independent
+chunk of changes. For example, you could have one branch for preparatory
+refactorings, one for backend changes, and one for frontend changes. Those
+branches would then all be stacked onto each other.
+
+Git has support for rebasing such a stack as a whole; you can enable it by
+setting the git config `rebase.updateRefs` to true. If you then rebase the
+topmost branch of the stack, the other ones in the stack will follow. This
+includes interactive rebases, so for example amending a commit in the first
+branch of the stack will "just work" in the sense that it keeps the other
+branches properly stacked onto it.
+
+Lazygit visualizes the individual branch heads in the stack by marking them with a
+cyan asterisk (or a cyan branch symbol if you are using [nerd
+fonts](Config.md#display-nerd-fonts-icons)).

docs-master/Searching.md

@@ -0,0 +1,24 @@
+# Undo/Redo in lazygit
+
+You can undo the last action by pressing 'z' and redo with `ctrl+z`. Here we drop a couple of commits and then undo the actions.
+Undo uses the reflog which is specific to commits and branches so we can't undo changes to the working tree or stash.
+
+![undo](../../assets/demo/undo-compressed.gif)
+
+## How it works
+
+If you're as clumsy as me you'll probably have felt the pain of botching an interactive rebase or doing a hard reset onto the wrong commit. Luckily, the reflog allows you to trace your steps and make things right again, but I personally can't stand trying to make sense of the reflog.
+
+Lazygit can read through your reflog for you and walk back action by action so that you don't even need to read the reflog. If lazygit finds a reflog entry where you checked out a branch, we'll checkout the original branch. If the entry is from a commit being applied, we'll go back to the commit before that. If we hit an interactive rebase, we'll go back to the commit you were on just before you started it.
+
+## You can even undo things you did outside of lazygit!
+
+Because lazygit just uses the reflog to keep track of things, it doesn't matter whether you're trying to undo something you did in lazygit or directly on the command line. You can open lazygit for the first time and start undoing thing in your repo! Likewise, lazygit marks its undos/redos in the reflog so if you quit the application and come back, lazygit still knows where you're up to.
+
+## Limitations
+
+There are limitations: firstly, lazygit can only undo things that are recorded in the reflog. That means changes to your working tree or stash aren't covered. Secondly, anything permanent you do like pushing to a remote can't be undone. Thirdly, actions like creating a branch won't be undone, because they're not stored in the reflog.
+
+If you are mid-rebase, undo/redo is not supported, because the reflog doesn't contain enough information about what specific things have happened inside that rebase. If you want to undo out of a rebase, it's best to abort the rebase (the default keybinding for bringing up rebase options is 'm').
+
+Undo/Redo is a new feature so if you find a bug let us know. The worst case scenario is that you'll just need to look at your reflog and manually put yourself back on track.

docs-master/Stacked_Branches.md

@@ -0,0 +1,78 @@
+# Knowing when Lazygit is busy/idle
+
+## The use-case
+
+This topic deserves its own doc because there are a few touch points for it. We have a use-case for knowing when Lazygit is idle or busy because integration tests follow the following process:
+1) press a key
+2) wait until Lazygit is idle
+3) run assertion / press another key
+4) repeat
+
+In the past the process was:
+1) press a key
+2) run assertion
+3) if assertion fails, wait a bit and retry
+4) repeat
+
+The old process was problematic because an assertion may give a false positive due to the contents of some view not yet having changed since the last key was pressed.
+
+## The solution
+
+First, it's important to distinguish three different types of goroutines:
+* The UI goroutine, of which there is only one, which infinitely processes a queue of events
+* Worker goroutines, which do some work and then typically enqueue an event in the UI goroutine to display the results
+* Background goroutines, which periodically spawn worker goroutines (e.g. doing a git fetch every minute)
+
+The point of distinguishing worker goroutines from background goroutines is that when any worker goroutine is running, we consider Lazygit to be 'busy', whereas this is not the case with background goroutines. It would be pointless to have background goroutines be considered 'busy' because then Lazygit would be considered busy for the entire duration of the program!
+
+In gocui, the underlying package we use for managing the UI and events, we keep track of how many busy goroutines there are using the `Task` type. A task represents some work being done by lazygit. The gocui Gui struct holds a map of tasks and allows creating a new task (which adds it to the map), pausing/continuing a task, and marking a task as done (which removes it from the map). Lazygit is considered to be busy so long as there is at least one busy task in the map; otherwise it's considered idle. When Lazygit goes from busy to idle, it notifies the integration test.
+
+It's important that we play by the rules below to ensure that after the user does anything, all the processing that follows happens in a contiguous block of busy-ness with no gaps.
+
+### Spawning a worker goroutine
+
+Here's the basic implementation of `OnWorker` (using the same flow as `WaitGroup`s):
+
+```go
+func (g *Gui) OnWorker(f func(*Task)) {
+	task := g.NewTask()
+	go func() {
+		f(task)
+		task.Done()
+	}()
+}
+```
+
+The crucial thing here is that we create the task _before_ spawning the goroutine, because it means that we'll have at least one busy task in the map until the completion of the goroutine. If we created the task within the goroutine, the current function could exit and Lazygit would be considered idle before the goroutine starts, leading to our integration test prematurely progressing.
+
+You typically invoke this with `self.c.OnWorker(f)`. Note that the callback function receives the task. This allows the callback to pause/continue the task (see below).
+
+### Spawning a background goroutine
+
+Spawning a background goroutine is as simple as:
+
+```go
+go utils.Safe(f)
+```
+
+Where `utils.Safe` is a helper function that ensures we clean up the gui if the goroutine panics.
+
+### Programmatically enqueueing a UI event
+
+This is invoked with `self.c.OnUIThread(f)`. Internally, it creates a task before enqueuing the function as an event (including the task in the event struct) and once that event is processed by the event queue (and any other pending events are processed) the task is removed from the map by calling `task.Done()`.
+
+### Pressing a key
+
+If the user presses a key, an event will be enqueued automatically and a task will be created before (and `Done`'d after) the event is processed.
+
+## Special cases
+
+There are a couple of special cases where we manually pause/continue the task directly in the client code. These are subject to change but for the sake of completeness:
+
+### Writing to the main view(s)
+
+If the user focuses a file in the files panel, we run a `git diff` command for that file and write the output to the main view. But we only read enough of the command's output to fill the view's viewport: further loading only happens if the user scrolls. Given that we have a background goroutine for running the command and writing more output upon scrolling, we create our own task and call `Done` on it as soon as the viewport is filled.
+
+### Requesting credentials from a git command
+
+Some git commands (e.g. git push) may request credentials. This is the same deal as above; we use a worker goroutine and manually pause continue its task as we go from waiting on the git command to waiting on user input. This requires passing the task through to the `Push` method so that it can be paused/continued.