Merge pull request #1815 from dolthub/fulghum/minor-doc-updates

Documentation for `dolt_reflog()` table function

Author: fulghum

content/reference/sql/version-control/branches.md

@@ -21,6 +21,17 @@ started, and can be changed for new connections with a [system
 variable](./dolt-sysvars.md#dbname_default_branch). Using database revision specifiers, clients can
 choose a specific branch, tag, or commit to pin their queries to.
 
+## Recovering a deleted branch
+The data on a branch is versioned, but the metadata of the branch head itself is not, so if you delete a 
+branch or reset it to point at an older commit, you can't revert or undo that change the same way you can 
+with your data. Instead, you can use 
+[the `dolt_reflog()` table function](./dolt-sql-functions.md#dolt_reflog) to see the history of commits
+your branch has referenced and either recreate the branch from the last referenced commit with 
+[the `dolt_branch()` stored procedure](./dolt-sql-procedures.md#dolt_branch) or reset the branch to a 
+previous commit with [the `dolt_reset()` stored procedure](./dolt-sql-procedures.md#dolt_reset). See
+[the `dolt_reflog()` table function](./dolt-sql-functions.md#dolt_reflog) for an example of recreating
+a deleted branch and more information on how the Dolt reflog works and what limitations it has.  
+
 ## Specify a database revision in the connection string
 
 The exact connection string you need to use will vary depending on your client.

content/reference/sql/version-control/dolt-sql-functions.md

@@ -19,6 +19,7 @@ title: Dolt SQL Functions
   - [dolt_diff_summary()](#dolt_diff_summary)
   - [dolt_log()](#dolt_log)
   - [dolt_patch()](#dolt_patch)
+  - [dolt_reflog()](#dolt_reflog)
   - [dolt_schema_diff](#dolt_schema_diff)
   - [dolt_query_diff](#dolt_query_diff)
 
@@ -806,6 +807,69 @@ With result of single row:
 +-----------------+------------------+----------------------------------+------------+-----------+---------------------+
 ```
 
+## `DOLT_REFLOG()`
+
+The `DOLT_REFLOG()` table function shows the history of named refs (e.g. branches and tags), which is useful when you want to understand how a branch or tag has changed over time to reference different commits, particularly for information that isn't surfaced through the `dolt_log` system table or `dolt_log()` table function. For example, if you use `dolt_reset()` to change the commit a branch points to, you can use `dolt_reflog()` to see what commit the branch was pointing to before it was moved to that commit. Another common use case for `dolt_reflog()` is to recreate a branch or tag that was accidentally deleted. The example section below shows how to recreate a deleted branch.  
+
+The data from Dolt's reflog comes from [Dolt's journaling chunk store](https://www.dolthub.com/blog/2023-03-08-dolt-chunk-journal/). This data is local to a Dolt database and never included when pushing, pulling, or cloning a Dolt database. This means when you clone a Dolt database, it will not have any reflog data until you perform operations that change what commit branches or tags reference.   
+
+Dolt's reflog is similar to [Git's reflog](https://git-scm.com/docs/git-reflog), but there are a few differences:
+- The Dolt reflog currently only supports named references, such as branches and tags, and not any of Git's special refs (e.g. `HEAD`, `FETCH-HEAD`, `MERGE-HEAD`).
+- The Dolt reflog can be queried for the log of references, even after a reference has been deleted. In Git, once a branch or tag is deleted, the reflog for that ref is also deleted and to find the last commit a branch or tag pointed to you have to use Git's special `HEAD` reflog to find the commit, which can sometimes be challenging. Dolt makes this much easier by allowing you to see the history for a deleted ref so you can easily see the last commit a branch or tag pointed to before it was deleted.
+
+### Privileges 
+
+There are no special privileges required to use the `dolt_reflog()` table function.
+
+### Options
+
+```sql
+DOLT_REFLOG()
+DOLT_REFLOG(<ref_name>)
+```
+
+The `dolt_reflog()` table function can be called with no arguments or with one argument. If called without any arguments, it will return the full reference log, which lists changes from newest to oldest for all tracked references. If called with one argument, that argument is the name of a ref to query. This can be the name of a branch (e.g. "myBranch") or the name of a tag (e.g. "v1.1.4") or it can be the fully qualified ref path (e.g. "refs/heads/myBranch"). The `ref_name` parameter is case-insensitive. 
+
+### Schema
+
+```text
++-----------------------+-----------+
+| field                 | type      |
++-----------------------+-----------+
+| ref                   | TEXT      |
+| ref_timestamp         | TIMESTAMP |
+| commit_hash           | TEXT      |
+| commit_message        | TEXT      |
++-----------------------+-----------+
+```
+
+### Example
+
+The example below shows how to recreate a branch that was deleted by finding the last commit it referenced in Dolt's reflog. 
+
+```sql
+-- Someone accidentally deletes the wrong branch!
+call dolt_branch('-D', 'prodBranch');
+
+-- After we realize the wrong branch has been deleted, we query the Dolt reflog on the same Dolt database instance
+-- where the branch was deleted to see what commits the prodBranch branch has referenced. Using the same Dolt 
+-- instance is important, since reflog information is always local and not included when pushing/pulling databases.
+select * from dolt_reflog('prodBranch');
++-----------------------+---------------------+----------------------------------+-------------------------------+
+| ref                   | ref_timestamp       | commit_hash                      | commit_message                |
++-----------------------+---------------------+----------------------------------+-------------------------------+
+| refs/heads/prodBranch | 2023-10-25 20:54:37 | v531ptpmv2tquig8v591tsjghtj84ksg | inserting row 42              |
+| refs/heads/prodBranch | 2023-10-25 20:53:12 | rvt34lqrbtdr3dhnjchruu73lik4e398 | inserting row 100000          |
+| refs/heads/prodBranch | 2023-10-25 20:53:06 | v531ptpmv2tquig8v591tsjghtj84ksg | inserting row 42              |
+| refs/heads/prodBranch | 2023-10-25 20:52:43 | ihuj1l7fmqq37sjhtlrgpup5n76gfhju | inserting row 1 into table xy |
++-----------------------+---------------------+----------------------------------+-------------------------------+
+
+-- The last commit prodBranch pointed to was v531ptpmv2tquig8v591tsjghtj84ksg, so to restore our branch, we
+-- just need to create a branch with the same name, pointing to that last commit.
+call dolt_branch('prodBranch', 'v531ptpmv2tquig8v591tsjghtj84ksg');
+```
+
+
 ## `DOLT_SCHEMA_DIFF()`
 
 The `DOLT_SCHEMA_DIFF()` table function calculates the schema difference between any two commits in the database.