github.com/hasnat/dolt/go@v0.0.0-20210628190320-9eb5d843fbb7/cmd/git-dolt/README.md (about)

     1  # Git-Dolt
     2  
     3  Git-Dolt: It's Git for data...in Git!
     4  
     5  ## Idea
     6  
     7  It should be easy to embed a Dolt repository inside a Git repository, and have
     8  changes tracked and synchronized without leaving Git.
     9  
    10  To this end, Git-Dolt creates persistent references to Dolt remotes in the form
    11  of pointer files. This approach is very similar to how [git-lfs](https://git-lfs.github.com/) embeds
    12  large binary files inside of Git repositories.
    13  
    14  A Git-Dolt pointer file specifies everything necessary to
    15  reconstruct (clone) the Dolt repository at a given revision:
    16  
    17  ```
    18  version 0
    19  remote http://dolthub.com/some-org/some-repo
    20  revision eidemcn2rsa5r1kpr5ds7mi0g5h8jt37
    21  ```
    22  
    23  In the future, we imagine `git-dolt` doing things like automatically proposing
    24  modifications to the pointer file when the cloned Dolt repo is modified. For
    25  now, if you want the pointer file to point to a different commit, you must update
    26  it manually; see the [`update`](#update) command below.
    27  
    28  ## Example
    29  
    30  ### Setup
    31  
    32  Make sure that `git-dolt` and `git-dolt-smudge` are in your PATH. Then do the steps below in a new directory somewhere:
    33  
    34  ```
    35  $ git init
    36  Initialized empty Git repository in /Users/mjesuele/dolt/git-dolt-smudge-test/.git/
    37  
    38  $ git dolt install
    39  Installed git-dolt smudge filter.
    40  When git-dolt pointer files are checked out in this git repository, the corresponding Dolt repositories will be automatically cloned.
    41  
    42  $ git dolt link Liquidata/lunch-places
    43  
    44  Dolt repository successfully linked!
    45  
    46  * Dolt repository cloned to lunch-places at revision qi331vjgoavqpi5am334cji1gmhlkdv5
    47  * Pointer file created at lunch-places.git-dolt
    48  * lunch-places added to .gitignore
    49  
    50  You should git commit these results.
    51  
    52  $ git add .
    53  
    54  $ git commit -m set up git-dolt integration
    55  [master (root-commit) 82c762e] set up git-dolt integration
    56   3 files changed, 5 insertions(+)
    57   create mode 100644 .gitattributes
    58   create mode 100644 .gitignore
    59   create mode 100644 lunch-places.git-dolt
    60  ```
    61  
    62  ### Testing the smudge filter
    63  
    64  ```
    65  $ rm -rf lunch-places lunch-places.git-dolt
    66  
    67  $ git checkout -- lunch-places.git-dolt
    68  Found git-dolt pointer file. Cloning remote Liquidata/lunch-places to revision qi331vjgoavqpi5am334cji1gmhlkdv5 in directory lunch-places...done.
    69  
    70  $ cd lunch-places
    71  
    72  $ dolt log -n 3
    73  commit qi331vjgoavqpi5am334cji1gmhlkdv5
    74  Author: bheni <brian@liquidata.co>
    75  Date:   Thu Jun 06 17:22:24 -0700 2019
    76  
    77  	update tocaya rating
    78  
    79  commit eidemcn2rsa5r1kpr5ds7mi0g5h8jt37
    80  Merge: 137qgvrsve1u458briekqar5f7iiqq2j ngfah8jf5r9apr7bds87nua9uavnlc1d
    81  Author: Aaron Son <aaron@liquidata.co>
    82  Date:   Thu Apr 18 13:04:18 -0700 2019
    83  
    84  	Merge...
    85  
    86  commit 137qgvrsve1u458briekqar5f7iiqq2j
    87  Author: bheni <brian@liquidata.co>
    88  Date:   Thu Apr 04 15:43:00 -0700 2019
    89  
    90  	change rating
    91  ```
    92  
    93  ## Commands
    94  
    95  ### install
    96  
    97  ```
    98  git dolt install
    99  ```
   100  
   101  Initializes a git-dolt integration in the current git repository by:
   102  
   103  1. Adding a line in `.gitattributes` declaring the git-dolt smudge filter on `.git-dolt` files.
   104  2. Adding a line in `.git/config` telling git which executable(s) to use for the git-dolt filter.
   105  
   106  Once this is done, any time a `.git-dolt` file is checked out in the git repository, the Dolt
   107  repository that it points to will automatically be cloned to the specified revision.
   108  
   109  Note that this functionality requires that the `git-dolt-smudge` executable be present in your `PATH`.
   110  
   111  See [the chapter in Pro Git on Git Attributes](https://git-scm.com/book/en/v2/Customizing-Git-Git-Attributes)
   112  for more information about filters.
   113  
   114  _Example:_
   115  
   116  ```
   117  $ git dolt install
   118  Installed git-dolt smudge filter. When git-dolt pointer files are checked out in this git repository, the corresponding Dolt repositories will be automatically cloned.
   119  
   120  You should git commit the changes to .gitattributes.
   121  ```
   122  
   123  ### link
   124  
   125  ```
   126  git dolt link <remote-url>
   127  ```
   128  
   129  Links a dolt remote to the current git repository by:
   130  
   131  1. Cloning the dolt repository in the current directory
   132  2. Adding the dolt repository directory to `.gitignore`
   133  3. Outputting a persistent `.git-dolt` pointer file intended to be committed with git
   134  
   135  _Example:_
   136  
   137  ```
   138  $ git dolt link http://localhost:50051/test-org/test-repo eidemcn2rsa5r1kpr5ds7mi0g5h8jt37
   139  
   140  Dolt repository successfully linked!
   141  
   142  * Dolt repository cloned to test-repo at revision jdnj4siav9lk8obprgfmsvlae4rvc5jc
   143  * Pointer file created at test-repo.git-dolt
   144  * test-repo added to .gitignore
   145  
   146  You should git commit these results.
   147  ```
   148  
   149  ### fetch
   150  
   151  ```
   152  git dolt fetch <pointer-file>
   153  ```
   154  
   155  Fetches a dolt repository from the remote and at the revision specified by the given git-dolt pointer file (you may omit the `.git-dolt` suffix when specifying this file).
   156  
   157  _Example:_
   158  
   159  ```
   160  $ git dolt fetch test-repo
   161  Dolt repository cloned from remote http://localhost:50051/test-org/test-repo to directory test-repo at revision 2diug5q1okrdi5rq4f8ct3vea00gblbj
   162  ```
   163  
   164  #### Note
   165  
   166  Currently, dolt lacks detached head support, meaning that you can't check out individual commits. It is also currently not possible to fetch only a specific revision from a remote repository.
   167  
   168  Accordingly, the current behavior of `git dolt fetch` is to clone the remote repository and create/check out a new branch called `git-dolt-pinned` which points at the specified commit.
   169  
   170  ### update
   171  
   172  ```
   173  git dolt update <pointer-file> <revision>
   174  ```
   175  
   176  Updates the given git-dolt pointer file to point to the specified revision.
   177  
   178  _Example:_
   179  
   180  ```
   181  $ git dolt update im-interested ppbq8n1difju3u02jf8iqmctd1ovbj76
   182  Updated pointer file im-interested.git-dolt to revision ppbq8n1difju3u02jf8iqmctd1ovbj76. You should git commit this change.
   183  ```
   184  
   185  ## Tests
   186  
   187  There are unit tests in Go and CLI tests using [BATS](https://github.com/sstephenson/bats).