diff -rN -u old-darcs-book/en/03-working-locally.md new-darcs-book/en/03-working-locally.md
--- old-darcs-book/en/03-working-locally.md	2024-11-24 01:48:20.261719963 +0000
+++ new-darcs-book/en/03-working-locally.md	2024-11-24 01:48:20.261719963 +0000
@@ -30,6 +30,10 @@
 hierarchy. For the rest of this chapter I will assume that we are inside of the
 `my-awesome-project` folder.
 
+If you want to create a `darcs` repository for an existing project, simply enter
+its directory and issue `darcs init`. `darcs` won't touch any of your work but
+will only initialize a repository.
+
 Ch-Ch-Ch Changes!
 -----------------
 
@@ -43,9 +47,8 @@
 Huh, `darcs` returns without reporting any patches. That's not very surprising
 since we have not recorded any yet.
 
-To warm up let's just create a simple "Hello World" program written in
-Haskell and add that change to our repository inside our newly created project
-folder.
+To warm up let's just create a simple "Hello World" program written in Haskell
+inside of our newly created project folder and add to our repository.
 
 ```
 $ echo 'main = putStrLn "Hello World!"' > Main.hs
@@ -53,9 +56,9 @@
 
 This creates a new file `Main.hs` with the content `main = putStrLn "Hello
 World"`, of course you can also use your favorite text editor to do this. By
-doing this we have changed our **working directory**.
+doing this we have changed our **working tree**.
 
-To find out what changes we have done to the working directory we can issue
+To find out what changes we have done to the working tree we can issue
 `darcs status`.
 
 ```
@@ -63,19 +66,21 @@
 a ./Main.hs
 ```
 
-What `darcs` does here is that it compares the state of your working directory
+What `darcs` does here is that it compares the state of your working tree
 against the state of the repository (recall that the state of the repository is
 a set of changes). In our current repository there are no recorded changes so
-adding something to our working directory surely should constitute a change
-shouldn't it?
+adding something to our working tree surely should constitute a change shouldn't
+it?
 
 Let's take a closer look at the output of `darcs status`. What does the lower
 case `a` in front of `./Main.hs` mean? Well, it means that the file `Main.hs` is
-currently **unadded**. Let's try to `record` a patch and see what happens.
+currently **unadded**, more on that in a second. Let's try to `record` a patch
+and see what happens.
 
 When we want to `record` a new patch we can simply issue `darcs record` and
-`darcs` will compare our current working directory against the state of our
-repository and consider all changes for the patch we are about to `record`.
+`darcs` will compare our current working tree against the state of our
+repository and consider all unrecorded changes for the patch we are about to
+`record`.
 
 ```
 $ darcs record
@@ -94,10 +99,10 @@
 A ./Main.hs
 ```
 
-Look at that! The lower case `a` changed to an upper case `A`, `darcs` is
-keeping track of changes to our `Main.hs` and we can now record our first
-change. If you want to have a list of all the files in your working directory
-that `darcs` keeps track of `darcs show files` is your friend.
+Look at that! The lower case `a` changed to an upper case `A`, `darcs` is now
+keeping track of changes to our `Main.hs` and we can record our first change. If
+you want to have a list of all the files in your working tree that `darcs` keeps
+track of `darcs show files` is your friend.
 
 ```
 $ darcs record -m 'add Main.hs'
@@ -122,11 +127,11 @@
 A lot of things happened here, so let's break it down.
 
 So what's with the `-m 'add Main.hs'`? That's actually the name we are giving
-this patch. We can later use it to refer to it it's also a small summary of what
-this patch is supposed to do. If you don't specify a name `darcs` will open your
-editor (which is specified by the `$EDITOR` environment variable) and you can
-provide the name there. Apart from only giving the patch a name you can also
-give some more detail about your new patch.
+this patch. We can later use it to refer to it and it's also a small summary of
+what this patch is supposed to do. If you don't specify a name `darcs` will open
+your text editor (which is specified by the `$EDITOR` environment variable) and
+you can provide the name there. Apart from only giving the patch a name you can
+also give some more detail about your new patch.
 
 The first thing that `darcs` does is asking us for our email, this makes sense
 because every patch needs an author. Once we tell `darcs` who we are it stores
@@ -136,7 +141,8 @@
 patch. The first one is that we simply want to add the `Main.hs` file the we
 created. The type of this change is `addfile`. The second change it asks us
 about adds the content to the file, this change type is what we call a `hunk`.
-This `hunk` just adds our single line program to the file.
+This `hunk` just adds our single line program as line 1 to `Main.hs` (indicated by
+the `+` in front of the line).
 
 `darcs log` will now show us our first recorded patch!
 
@@ -176,13 +182,62 @@
 changes for this chapter of the book I would say `darcs record
 en/02-getting-started.md`.
 
+Recursively adding files
+------------------------
+
+When you need to add quite a lot of files all at once you don't want to do that
+one by one. `add` offers a `--resursive` flag and its short hand `-r` which
+instructs `add` to traverse the working tree and add as yet **unadded** files.
+Let me show you.
+
+Here we create just a couple of files and add them all at once.
+
+```
+$ mkdir quux
+$ touch foo bar baz quux/foo quux/bar quux/baz
+$ darcs add -r .
+Adding 'bar'
+Adding 'baz'
+Adding 'foo'
+Adding 'quux'
+Adding 'quux/bar'
+Adding 'quux/baz'
+Adding 'quux/foo'
+$ darcs status
+A ./bar
+A ./baz
+A ./foo
+A ./quux/
+A ./quux/bar
+A ./quux/baz
+A ./quux/foo
+```
+
+Hrm, now we have quite a lot of new changes and when we want to `record` them
+`darcs` will prompt us for each of them if we want to `record` that change. But
+as we have learned in the previous section `record` offers a flag `-a` that
+automatically says `yes` to all unrecorded changes. I think this is a good time
+to demonstrate this.
+
+```
+$ darcs record -a -m 'a lot of new files'
+Finished recording patch 'a lot of new files'
+```
+
+BAMM! Seven with one stroke! While interactive commands are really helpful most
+of the time, sometimes we need to be able to express our intent with as little
+work as possible, and `darcs` can do exactly that without getting in our way.
+
+If you accidentally added a file that you didn't want to `add` you can use
+`darcs remove FILENAME` and the file in question will become **unadded** again.
+
 Removing a file
 ---------------
 
-At some point we might want to get rid of a file in our repository. You can
-simply delete the file and record a new change. Don't worry, your file is still
-contained in the history if you recorded it earlier, so you can always get it
-back.
+At some point we might want to get rid of a file in our repository. We don't
+really need `remove` for that. You can simply delete the file and record a new
+change. Don't worry, your file is still contained in the history if you recorded
+it earlier, so you can always get it back.
 
 ```
 $ rm Main.hs
@@ -257,17 +312,23 @@
 +main = putStrLn "Hello Everyone!"
 ```
 
-So `darcs` has swapped out the entire line just because we have changed a single
-word as indicated by the `hunk` change. If we wanted to we can record a new
-patch based on this patch but let's look at another way to do something like
-this.
+`darcs whatsnew` has detected a `hunk` change that has happened to line 1. What
+is does it that is removes the entire line 1 (indicated by the `-` at the
+beginning of the line) and adds a new line (indicated by the `+`). So `darcs`
+has swapped out the entire line just because we have changed a single word as
+indicated by the `hunk` change. If we wanted to we can record a new patch based
+on this patch but let's look at another way to do something like this.
 
 One thing I like to do when revisiting my unrecorded changes is to use `whatsnew
 -i` which puts the command into interactive mode. That way I can step through
 all of the changes one by one rather that scrolling through what can be
 potentially a lot of output.
 
-A little side note, `status` is basically just an alias for `whatsnew -ls`.
+A little side note, `status` is basically just an alias for `whatsnew -ls` where
+`-s` is a short hand for `--summary` and `-l` is a short hand for
+`--look-for-add`. The former gives us the nice concise description of the
+unrecorded changes in our working tree, the latter searches for **unadded**
+files.
 
 Seek and replace
 ----------------
@@ -291,12 +352,13 @@
 
 Remember that **unadded** files are displayed with a lower case `a` in the `darcs
 status` output? This can be a bit annoying because there might be some files in
-our working directory that we would never consider for a patch. For files like
+our working tree that we would never consider for a patch. For files like
 this we have a list of files that we consider **boring**.
 
-Here's an example. We now have our `Hello.hs` file in our working directory and
-we want to compile that program. When we take a look at the our `status` we get
-a surprise.
+Here's an example. We now have our `Hello.hs` file in our working tree and we
+want to compile that program, when we do that our compiler will emit a new
+binary file `Hello`. Now, if we take a look at the our `status` we get a
+surprise.
 
 ```
 $ darcs status
@@ -304,12 +366,14 @@
 ```
 
 Hm, so now `Hello` is considered **unadded** but we never want to add it to the
-repository anyway. This situation might not be so bad but image you have a bunch
-of these files. Your `status` output will soon become cluttered with files you
-actually want to ignore. To help is with this `darcs` maintains a **boring**
-file under `_darcs/prefs/boring`. This file contains a list of regular
-expressions to filter out files we are not interested in for version control. We
-can simply add our `Hello` file to it and won't be bothered with it anymore.
+repository anyway, it's a good common practice to only track the source code of
+a project rather than the product. This situation might not be so bad but
+imagine you have a bunch of these files. Your `status` output will soon become
+cluttered with files you actually want to ignore and things will get confusing
+pretty quickly. To help with this `darcs` maintains a **boring** file under
+`_darcs/prefs/boring`. This file contains a list of regular expressions to
+filter out files we are not interested in for version control. We can simply add
+our `Hello` file to it and won't be bothered with it anymore.
 
 ```
 $ darcs status
@@ -327,11 +391,12 @@
 ------------------
 
 We briefly looked at `darcs log` to take a look at our recorded patches. One of
-the useful utilities of `log` is the `-v` flag that displays the changes that a
-certain patch represents. That might be a little to much sometimes, think about
-adding a large new text file to your repository. You almost certainly don't want
-to see that entire file in you `log` output. The `-s` flag allows you just to
-look at a summary of changes, similar to the `darcs status` output.
+the useful utilities of `log` is the `-v` flag which is a short hand for
+`--verbose` and it displays the changes that a certain patch represents. That
+might be a little to much sometimes, think about adding a large new text file to
+your repository. You almost certainly don't want to see that entire file in you
+`log` output. The `-s` flag which is a short hand for `--summary` allows you
+just to look at a summary of changes, similar to the `darcs status` output.
 
 ```
 $ darcs log -s
@@ -373,7 +438,7 @@
 
 ```
 
-Sometimes you just want to look at certain patches here is where the name we
+Sometimes you just want to look at certain patches, this is where the name we
 provide whenever we are recording a new patch comes in handy. `log` takes a `-p`
 that allows us to specify a regular expression and `darcs log` will pick out
 only the patches where the regular expression matches the name.
@@ -387,14 +452,14 @@
 ```
 $ darcs log -p dunst -s
 patch 81fac56462c274f8a507f9e5497c22e8d418cae9
-Author: raichoo <raichoo@example.com>
+Author: raichoo@example.com
 Date:   Tue Apr 17 17:48:15 CEST 2018
   * key shortcut to close dunst notifications
 
     M ./dunst/dunstrc -2 +2
 
 patch 0743c619f5cf0d67fc9d36de96f83752c3c56b12
-Author: raichoo <raichoo@example.com>
+Author: raichoo@example.com
 Date:   Fri Mar 30 18:28:54 CEST 2018
   * add dunst config