Overview of existing and missing content

[adswa]

Based on the diagram in #3, and the DataLad documentation, here is a list of commands and arguments that should be demonstrated in the book. Please add commands or opinions on options you want to see in there.

Currently, I'm just copying the available options and arguments from the docs, and just because it's listed here, the command does not necessarily need to go into the book. Cross out anything you deem unnecessary by surrounding the line with ~~ like this.

Everything that is ticked is demonstrated or at least referenced somewhere in the book already.

Eventually, this can become a bit of a guide about possible contributions by others.

Core local DataLad commands

• datalad status

  • "bare" datalad status
    • explanations of datalad status content types (dataset, directory, file, symlink)
    • explanations of datalad status content states (clean, added, modified, untracked)
    • datalad status with path specification
  • datalad status --annex
    • datalad status --annex all
    • datalad status --annex availability
  • datalad status --recursive and datalad status --recursive --recursion-limit
  • datalad status --untracked
    • datalad status --untracked no
    • datalad status --untracked all

• datalad create

  • "bare" datalad create
    • When things go wrong: Creation attempt in non-empty directory
  • datalad create --dataset
    • When things go wrong: No installed dataset found
  • datalad create PATH (not demonstrated, but talked about)
  • datalad create --description
  • configuration options
    • -c text2git
    • --no annex
    • --nosave False
    • --annex-version
    • --annex-backend
    • --native-metadata-type

• datalad diff

  • "bare" datalad diff
    • explanations of datalad diff change states (added, copied, deleted, modified, renamed, typechange, unmerged, untracked)
  • datalad diff --staged
  • datalad diff --revision
  • datalad diff --ignore-subdatasets
  • datalad diff --report-untracked
  • datalad diff --recursive and --recursion-limit

• datalad save

  • "bare" datalad save
    • When things go wrong: Explain that save saves all modifications and untracked content
  • datalad save -m
    • When things go wrong: Forgot the commit message
    • -F/--message-file as an alternative
  • datalad save PATH
  • datalad save -u
  • datalad save -S/--super-datasets
  • datalad save --version-tag
  • datalad save --recursive and --recursion-limit

• datalad run

  • "bare" datalad run
    • with a script
    • with bash command
  • datalad run -m
  • datalad run options
    • datalad run --input
    • datalad run --output
    • datalad run --explicit
    • datalad run --sidecar
    • datalad run --expand

• datalad containers-run

  • datalad containers-add
  • datalad containers-run
  • datalad containers-remove
  • datalad containers-list

Advanced local DataLad commands

• datalad rerun

  • "bare" datalad rerun
    • with a script
    • with bash command
  • datalad rerun -m
  • datalad rerun options
    • datalad rerun --since
    • datalad rerun --onto
    • datalad rerun --branch
    • datalad run --report --script

• datalad run-procedure

  • datalad run-procedure
    • which one do actually exist? What does it do? How to get help on a procedure
    • datalad run-procedure --discover

• datalad uninstall

  • "bare" datalad uninstall subdataset
    • When things go wrong: specify nothing or non-dataset
  • datalad uninstall --nocheck
  • datalad uninstall --if-dirty options
  • datalad rerun --recursive

• datalad remove

  • "bare" datalad remove
    • Files
    • (non)empty directories
    • When things go wrong: no remote copies
  • datalad remove -m
  • datalad remove --nocheck
  • datalad remove --nosave options
  • datalad remove --if-dirty options
  • datalad remove --recursive

• datalad publish

  • "bare" datalad publish --to
  • explain ``--transfer-data {all|auto|none}
  • recursive and recursion-limit

[...to be continued (fuck)]

Advanced distributed DataLad commands

!!! datalad install was replaced with datalad clone in #321 and #326 !!!

• datalad install

  • "bare" datalad install
    • with path
    • without path
  • datalad install -d as subdataset
    • with path
    • without path
  • datalad install --recursive --recursion-limit
  • datalad install --nosave
  • datalad install --reckless
  • datalad install --get-data
  • datalad install --jobs

• datalad clone

  • "bare" datalad clone
    • with path
    • without path
  • datalad clone -d as subdataset
    • with path
    • without path

• datalad get

  • "bare" datalad get
    • with specific path
    • with . (mentioned)
    • files
    • directories
    • subdatasets
    • datalad get --recursive --recursion-limit
  • When things go wrong
    • timeouts
    • all kinds of error messages this thing can throw
    • datalad get --verbose
  • datalad get --no-data
  • datalad get --reckless
  • datalad get --jobs

• datalad drop

  • "bare" datalad drop
  • datalad drop --recursive --recursion-limit
  • datalad drop --nocheck
  • datalad drop --if-dirty
  • When things go wrong: If file content is not available elsewhere

• datalad siblings

  • Concept: What is a sibling
  • Actions: query, add, remove, configure
  • there are many many options...

• datalad update

  • "bare" datalad update
    • talk about siblings and sibling option
    • datalad update --merge
    • datalad update --reobtain-data
    • datalad update --recursive --recursion-limit

• datalad publish

  • minimal datalad publish

Git specific commands and concepts

• What is HEAD?
  • DETACHED HEAD STATE
• git log
  • mention tig
• branches
  • Explain
  • how to work with them, commands
• git diff
• History
  • git commit --amend
  • git revert
  • git checkout
  • git rebase
  • git reset
• git status
• git commit
• git add
• git config, and configuration(file)s
• environment variables for configurations

Git-annex specific commands

• Git repository version
• the object tree
• git-annex fsck
• git-annex fix
• What is the git-annex branch, what to do and what not to do
• Git annex v5/v6/v7 repositories

Misc

• how to get help on any command with -h/--help
• man pages
• datalad wtf, datalad --version
• general explanation of the -d/--dataset option
• The datalad superdataset ///
• Showcase how changes in subdataset look in superdataset

[adswa]

mention the idea of "Always look down, not up": DataLad only cares about lower-level subdatasets, and only in a single occasion ever looks upwards

[adswa]

This issue is a never ending rabbit hole - it has served its initial purpose.