Debian Codegraph @

docs/source/basics_nesteddatasets.rst.in

raw
1 .. The content of this file was auto-generated by your mad uncle from Germany
2 using the cast2rst script and a recorded asciicast as input.
3
4 Do not edit this file!
5
6
7
8 DataLad provides seamless management of nested Git repositories...
9
10 Let's create a dataset
11
12 .. code-block:: ansi-color
13
14 ~ % datalad create demo
15 [INFO ] Creating a new annex repo at /demo/demo
16 create(ok): /demo/demo (dataset)
17 ~ % cd demo
18
19
20 A DataLad dataset is just a Git repo with some initial configuration
21
22 .. code-block:: ansi-color
23
24 ~/demo % git log --oneline
25 472e34b (HEAD -> master) [DATALAD] new dataset
26 f968257 [DATALAD] Set default backend for all files to be MD5E
27
28
29 We can generate nested datasets, by telling DataLad to register a
30 new dataset in a parent dataset
31
32 .. code-block:: ansi-color
33
34 ~/demo % datalad create -d . sub1
35 [INFO ] Creating a new annex repo at /demo/demo/sub1
36 add(ok): sub1 (dataset) [added new subdataset]
37 add(notneeded): sub1 (dataset) [nothing to add from /demo/demo/sub1]
38 add(notneeded): .gitmodules (file) [already included in the dataset]
39 save(ok): /demo/demo (dataset)
40 create(ok): sub1 (dataset)
41 action summary:
42 add (notneeded: 2, ok: 1)
43 create (ok: 1)
44 save (ok: 1)
45
46
47 A subdataset is nothing more than regular Git submodule
48
49 .. code-block:: ansi-color
50
51 ~/demo % git submodule
52 5f0cddf2026e3fb4864139f27e7415fd72c7d4d0 sub1 (heads/master)
53
54
55 Of course subdatasets can be nested
56
57 .. code-block:: ansi-color
58
59 ~/demo % datalad create -d . sub1/justadir/sub2
60 [INFO ] Creating a new annex repo at /demo/demo/sub1/justadir/sub2
61 add(ok): sub1/justadir/sub2 (dataset) [added new subdataset]
62 add(notneeded): sub1/justadir/sub2 (dataset) [nothing to add from /demo/demo/sub1/justadir/sub2]
63 add(notneeded): sub1/.gitmodules (file) [already included in the dataset]
64 add(notneeded): sub1 (dataset) [already known subdataset]
65 save(ok): /demo/demo/sub1 (dataset)
66 save(ok): /demo/demo (dataset)
67 create(ok): sub1/justadir/sub2 (dataset)
68 action summary:
69 add (notneeded: 3, ok: 1)
70 create (ok: 1)
71 save (ok: 2)
72
73
74 Unlike Git, DataLad automatically takes care of committing all
75 changes associated with the added subdataset up to the given
76 parent dataset
77
78 .. code-block:: ansi-color
79
80 ~/demo % git status
81 On branch master
82 nothing to commit, working tree clean
83
84
85 Let's create some content in the deepest subdataset
86
87 .. code-block:: ansi-color
88
89 ~/demo % mkdir sub1/justadir/sub2/anotherdir
90 ~/demo % touch sub1/justadir/sub2/anotherdir/afile
91
92
93 Git can only tell us that something underneath the top-most
94 subdataset was modified
95
96 .. code-block:: ansi-color
97
98 ~/demo % git status
99 On branch master
100 Changes not staged for commit:
101 (use "git add <file>..." to update what will be committed)
102 (use "git checkout -- <file>..." to discard changes in working directory)
103 (commit or discard the untracked or modified content in submodules)
104
105 modified: sub1 (untracked content)
106
107 no changes added to commit (use "git add" and/or "git commit -a")
108
109
110 DataLad saves us from further investigation
111
112 .. code-block:: ansi-color
113
114 ~/demo % datalad diff -r
115 modified(dataset): sub1
116 modified(dataset): sub1/justadir/sub2
117 untracked(directory): sub1/justadir/sub2/anotherdir
118
119
120 Like Git, it can report individual untracked files, but also across
121 repository boundaries
122
123 .. code-block:: ansi-color
124
125 ~/demo % datalad diff -r --report-untracked all
126 modified(dataset): sub1
127 modified(dataset): sub1/justadir/sub2
128 untracked(file): sub1/justadir/sub2/anotherdir/afile
129
130
131 Adding this new content with Git or git-annex would be an exercise
132
133 .. code-block:: ansi-color
134
135 ~/demo % git add sub1/justadir/sub2/anotherdir/afile
136 fatal: Pathspec 'sub1/justadir/sub2/anotherdir/afile' is in submodule 'sub1'
137
138
139 DataLad does not require users to determine the correct repository
140 in the tree
141
142 .. code-block:: ansi-color
143
144 ~/demo % datalad add -d . sub1/justadir/sub2/anotherdir/afile
145 add(ok): sub1/justadir/sub2/anotherdir/afile (file)
146 save(ok): /demo/demo/sub1/justadir/sub2 (dataset)
147 save(ok): /demo/demo/sub1 (dataset)
148 save(ok): /demo/demo (dataset)
149 action summary:
150 add (ok: 1)
151 save (ok: 3)
152
153
154 Again, all associated changes in the entire dataset tree, up to
155 the given parent dataset, were committed
156
157 .. code-block:: ansi-color
158
159 ~/demo % git status
160 On branch master
161 nothing to commit, working tree clean
162
163
164 DataLad's 'diff' is able to report the changes from these related
165 commits throughout the repository tree
166
167 .. code-block:: ansi-color
168
169 ~/demo % datalad diff --revision @~1 -r
170 modified(dataset): sub1
171 modified(dataset): sub1/justadir/sub2
172 added(file): sub1/justadir/sub2/anotherdir/afile
173
174
175 _____________________________________
176 / Demo was using datalad 0.9.2.dev1. \
177 \ Discover more at http://datalad.org /
178 -------------------------------------
179 \ ^__^
180 \ (oo)\_______
181 (__)\ )\/\
182 ||----w |
183 || ||
184
185
186 .. code-block:: ansi-color
187
188 ~/demo % exit