.. _modify:

Modify content
--------------

So far, we've only added new content to the dataset. And we haven't done
much to that content up this point, to be honest. Let's see what happens if
we add content, and then modify it.

For this, in the root of ``DataLad-101``, create a simple text file
called ``notes.txt``. This will contain all of the notes that you take
throughout the course.

Pick an editor of your choice and write a short summary of how to create
a DataLad dataset from scratch. Below is one way to do it, using the
``cat`` command that comes with any Unix system, and a simple redirection
with ``>``. Running the command below will create ``notes.txt`` in the
root of your ``DataLad-101`` dataset:

.. runrecord:: _examples/DL-101-103-101
   :language: console
   :workdir: dl-101/DataLad-101

   $ cat << EOT > notes.txt
   One can create a new dataset with 'datalad create [--description] PATH'.
   The dataset is created empty

   EOT

Run :command:`datalad status` to confirm that there is new, untracked content:

.. runrecord:: _examples/DL-101-103-102
   :language: console
   :workdir: dl-101/DataLad-101

   $ datalad status

Save this file in its current state. Because it is the only modification
in the dataset, there is no need to specify a path.

.. runrecord:: _examples/DL-101-103-103
   :language: console
   :workdir: dl-101
   :realcommand: cd DataLad-101 && datalad save -m "Add notes on datalad create" notes.txt

   $ datalad save -m "Add notes on datalad create"

Modify this file by adding another note. After all, you already know how use
:command:`datalad save`, so write a short summary on that as well.

Again, the example below uses Unix commands (``cat`` and redirecting, this time however
with ``>>`` to *append* new content to the existing file)
to accomplish this, but you can take any editor of your choice.

.. runrecord:: _examples/DL-101-103-104
   :language: console
   :workdir: dl-101/DataLad-101

   $ cat << EOT >> notes.txt
   The command "datalad save [-m] PATH" saves the file
   (modifications) to history. Note to self:
   Always use informative, concise commit messages.

   EOT

Let's check the dataset's current state:

.. runrecord:: _examples/DL-101-103-105
   :language: console
   :workdir: dl-101/DataLad-101

   $ datalad status

and save the file:

.. runrecord:: _examples/DL-101-103-106
   :language: console
   :workdir: dl-101/DataLad-101

   $ datalad save -m "add note on datalad save"

Let's take another look into our history to see the development of this file.
We're using :command:`git log -p` to see the difference to the previous state of a
file within each commit. (Note: the output below is an excerpt, if you enter
the git log, your history will be longer, and thus opened in a
`pager <https://en.wikipedia.org/wiki/Terminal_pager>`_. You can get out of it by pressing ``q``.

.. runrecord:: _examples/DL-101-103-107
   :language: console
   :workdir: dl-101/DataLad-101
   :lines: 1-28
   :emphasize-lines: 6, 25, 27

   $ git log -p

We can see that the history can not only show us the commit message attached to
a commit, but also the precise change that occurred in the text file in the commit.
Additions are marked with a ``+``, and deletions would be shown with a leading ``-``.
That's quite neat, isn't it?
