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).