Skip to content

Commit

Permalink
Merge pull request #1003 from swcarpentry/recipes-draft
Browse files Browse the repository at this point in the history 
Recipes draft
  • Loading branch information
@martinosorb
martinosorb authored Sep 29, 2024
2 parents db7155f + 11f8316 commit ecbc85e
Show file tree
Hide file tree
Showing 15 changed files with 654 additions and 557 deletions.
12 changes: 6 additions & 6 deletions episodes/02-setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,14 +27,14 @@ of configurations we will set as we get started with Git:

On a command line, Git commands are written as `git verb options`,
where `verb` is what we actually want to do and `options` is additional optional information which may be needed for the `verb`. So here is how
Dracula sets up his new laptop:
Alfredo sets up his new laptop:

```bash
$ git config --global user.name "Vlad Dracula"
$ git config --global user.email "vlad@tran.sylvan.ia"
$ git config --global user.name "Alfredo Linguini"
$ git config --global user.email "a.linguini@ratatouille.fr"
```

Please use your own name and email address instead of Dracula's. This user name and email will be associated with your subsequent Git activity,
Please use your own name and email address instead of Alfredo's. This user name and email will be associated with your subsequent Git activity,
which means that any changes pushed to
[GitHub](https://github.com/),
[BitBucket](https://bitbucket.org/),
Expand Down Expand Up @@ -84,7 +84,7 @@ $ git config --global core.autocrlf true

::::::::::::::::::::::::::::::::::::::::::::::::::

Dracula also has to set his favorite text editor, following this table:
Alfredo also has to set his favorite text editor, following this table:

| Editor | Configuration command |
| :----------- | :------------------------------ |
Expand Down Expand Up @@ -118,7 +118,7 @@ If you want to save your changes and quit, press <kbd>Esc</kbd> then type `:wq`
::::::::::::::::::::::::::::::::::::::::::::::::::

Git (2.28+) allows configuration of the name of the branch created when you
initialize any new repository. Dracula decides to use that feature to set it to `main` so
initialize any new repository. Alfredo decides to use that feature to set it to `main` so
it matches the cloud service he will eventually use.

```bash
Expand Down
75 changes: 30 additions & 45 deletions episodes/03-create.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,32 +20,17 @@ exercises: 0
Once Git is configured,
we can start using it.

We will continue with the story of Wolfman and Dracula who are investigating if it
is possible to send a planetary lander to Mars.

![](fig/motivatingexample.png){alt='The main elements of the story: Dracula, Wolfman, the Mummy, Mars, Pluto and The Moon'}
[Werewolf vs dracula](https://www.deviantart.com/b-maze/art/Werewolf-vs-Dracula-124893530)
by [b-maze](https://www.deviantart.com/b-maze) / [Deviant Art](https://www.deviantart.com/).
[Mars](https://en.wikipedia.org/wiki/File:OSIRIS_Mars_true_color.jpg) by European Space Agency /
[CC-BY-SA 3.0 IGO](https://creativecommons.org/licenses/by/3.0/deed.en).
[Pluto](https://commons.wikimedia.org/wiki/File:PIA19873-Pluto-NewHorizons-FlyingPastImage-20150714-transparent.png) /
Courtesy NASA/JPL-Caltech.
[Mummy](https://commons.wikimedia.org/wiki/File:Mummy_icon_-_Noun_Project_4070.svg)
© Gilad Fried / [The Noun Project](https://thenounproject.com/) /
[CC BY 3.0](https://creativecommons.org/licenses/by/3.0/deed.en).
[Moon](https://commons.wikimedia.org/wiki/File:Lune_ico.png)
© Luc Viatour / [https://lucnix.be](https://lucnix.be/) /
[CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/deed.en).
We will help Alfredo with his new project, create a repository with all his recipes.

First, let's create a new directory in the `Desktop` folder for our work and then change the current working directory to the newly created one:

```bash
$ cd ~/Desktop
$ mkdir planets
$ cd planets
$ mkdir recipes
$ cd recipes
```

Then we tell Git to make `planets` a [repository](../learners/reference.md#repository)
Then we tell Git to make `recipes` a [repository](../learners/reference.md#repository)
\-- a place where Git can store versions of our files:

```bash
Expand All @@ -54,9 +39,9 @@ $ git init

It is important to note that `git init` will create a repository that
can include subdirectories and their files---there is no need to create
separate repositories nested within the `planets` repository, whether
separate repositories nested within the `recipes` repository, whether
subdirectories are present from the beginning or added later. Also, note
that the creation of the `planets` directory and its initialization as a
that the creation of the `recipes` directory and its initialization as a
repository are completely separate processes.

If we use `ls` to show the directory's contents,
Expand All @@ -67,7 +52,7 @@ $ ls
```

But if we add the `-a` flag to show everything,
we can see that Git has created a hidden directory within `planets` called `.git`:
we can see that Git has created a hidden directory within `recipes` called `.git`:

```bash
$ ls -a
Expand Down Expand Up @@ -103,33 +88,33 @@ wording of the output might be slightly different.

## Places to Create Git Repositories

Along with tracking information about planets (the project we have already created),
Dracula would also like to track information about moons.
Despite Wolfman's concerns, Dracula creates a `moons` project inside his `planets`
Along with tracking information about recipes (the project we have already created),
Alfredo would also like to track information about desserts specifically.
Alfredo creates a `desserts` project inside his `recipes`
project with the following sequence of commands:

```bash
$ cd ~/Desktop # return to Desktop directory
$ cd planets # go into planets directory, which is already a Git repository
$ ls -a # ensure the .git subdirectory is still present in the planets directory
$ mkdir moons # make a subdirectory planets/moons
$ cd moons # go into moons subdirectory
$ git init # make the moons subdirectory a Git repository
$ ls -a # ensure the .git subdirectory is present indicating we have created a new Git repository
$ cd ~/Desktop # return to Desktop directory
$ cd recipes # go into recipes directory, which is already a Git repository
$ ls -a # ensure the .git subdirectory is still present in the recipes directory
$ mkdir desserts # make a sub-directory recipes/desserts
$ cd desserts # go into desserts subdirectory
$ git init # make the desserts subdirectory a Git repository
$ ls -a # ensure the .git subdirectory is present indicating we have created a new Git repository
```

Is the `git init` command, run inside the `moons` subdirectory, required for
tracking files stored in the `moons` subdirectory?
Is the `git init` command, run inside the `desserts` subdirectory, required for
tracking files stored in the `desserts` subdirectory?

::::::::::::::: solution

## Solution

No. Dracula does not need to make the `moons` subdirectory a Git repository
because the `planets` repository can track any files, sub-directories, and
subdirectory files under the `planets` directory. Thus, in order to track
all information about moons, Dracula only needed to add the `moons` subdirectory
to the `planets` directory.
No. Alfredo does not need to make the `desserts` subdirectory a Git repository
because the `recipes` repository will track all files, sub-directories, and
subdirectory files under the `recipes` directory. Thus, in order to track
all information about desserts, Alfredo only needed to add the `desserts` subdirectory
to the `recipes` directory.

Additionally, Git repositories can interfere with each other if they are "nested":
the outer repository will try to version-control
Expand All @@ -151,9 +136,9 @@ fatal: Not a git repository (or any of the parent directories): .git

## Correcting `git init` Mistakes

Wolfman explains to Dracula how a nested repository is redundant and may cause confusion
down the road. Dracula would like to go back to a single git repository. How can Dracula undo
his last `git init` in the `moons` subdirectory?
Jimmy explains to Alfredo how a nested repository is redundant and may cause confusion
down the road. Alfredo would like to go back to a single git repository. How can Alfredo undo
his last `git init` in the `desserts` subdirectory?

::::::::::::::: solution

Expand All @@ -176,11 +161,11 @@ becomes another change that we will need to track, as we will see in the next ep
### Solution

Git keeps all of its files in the `.git` directory.
To recover from this little mistake, Dracula can remove the `.git`
folder in the moons subdirectory by running the following command from inside the `planets` directory:
To recover from this little mistake, Alfredo can remove the `.git`
folder in the desserts subdirectory by running the following command from inside the `recipes` directory:

```bash
$ rm -rf moons/.git
$ rm -rf desserts/.git
```

But be careful! Running this command in the wrong directory will remove
Expand Down
Loading

0 comments on commit ecbc85e

Please sign in to comment.