VSinerva/freesewing
1
0
Fork 0
Code Activity

[studio] fix: Corrections to add documentation (#317)

Browse source 
Replaces #289 by @BenJamesBen which was blocked due to a  merge conflict.

Co-authored-by: Benjamin Fan <ben-git@swinglonga.com>
Reviewed-on: https://codeberg.org/freesewing/freesewing/pulls/317
Co-authored-by: joostdecock <joost@joost.at>
Co-committed-by: joostdecock <joost@joost.at>
This commit is contained in:
joostdecock 2025-05-01 14:42:44 +00:00 • committed by Joost De Cock
parent 48b11c2016
commit 87834e5ab2
2 changed files with 124 additions and 116 deletions
Download patch file Download diff file Expand all files Collapse all files

2
packages/studio/template/docs/add.mdx
View file

@ -9,5 +9,5 @@ folder of your studio setup:
npm run add
```
It will prompt you for your design name, and as whether you want to create a
It will prompt you for your design name, and ask whether you want to create a
design from scratch, or start from a block.

194
sites/dev/docs/training/git/readme.mdx
View file

@ -30,7 +30,6 @@ or **[video series][video]**.
[audio]: /training/git/audio/
[video]: /training/git/video/
## Chapter 1: Welcome
Hello everyone and welcome to this **git** training.
@ -86,7 +85,7 @@ So let's meet a few of them.
## Chapter 3: Version control systems
One of the first version control systems (or VCS) was `sccs`, which stands for
*Source Code Control System*. From its name, we can learn that the origins of
_Source Code Control System_. From its name, we can learn that the origins of
version control systems can be traced back to software developers. They were
the first group of people who not only faced this problem of working together
on a bunch of files, but also had the means to come up with a way to make it
@ -95,8 +94,8 @@ more efficient.
SCCS was first released in 1973 which most likely means that version control
systems have been around for longer than you've been alive.
Almost 10 years later, in 1982, RCS was released. It stands for *Revision
Control System* and to this day, it is still maintained. Where RCS was intended
Almost 10 years later, in 1982, RCS was released. It stands for _Revision
Control System_ and to this day, it is still maintained. Where RCS was intended
to be used locally on a computer system, new systems emerged that relied on a
centralized repository to allow people to collaborate from different systems.
@ -179,27 +178,27 @@ out of the sky when we make a mistake.
Git is built on the combination of two concepts, and you're probably already
somewhat familiar with both of them.
The first concept is the so-called DAG. Which stands for *Directed
Acyclic Graph*. A *graph* in computer science and mathematics alike is
The first concept is the so-called DAG. Which stands for _Directed
Acyclic Graph_. A _graph_ in computer science and mathematics alike is
a structure in which we can store not only information, but also relationships
between that information.
You may have heard of Facebook's *social graph*, which holds information about
You may have heard of Facebook's _social graph_, which holds information about
Facebook's users, but also information about the relationships between those
users. Alice, Bob, Tony, Jim, and Sandra are all Facebook users.
In addition, Alice is a friend of Bob. Bob's father is Tony. Tony works at
McDonalds. Jim and Sandra also work at McDonalds.
We call this sort of data structure a *graph*. The users themselves are the
*nodes* of the graph. Each node holds the data for one user.
The relationships between users are the *edges* of the graph.
We call this sort of data structure a _graph_. The users themselves are the
_nodes_ of the graph. Each node holds the data for one user.
The relationships between users are the _edges_ of the graph.
If we visualize this structure, the users or nodes of the graph would be
represented by points or little circles. The relationships between the user or
edges of the graph would be lines that we draw between the users to show
how they are connected to each other.
![A graph](graph.png "Example of a graph")
![A graph](graph.png 'Example of a graph')
Git stores its data in a graph structure, but not one like Facebook's social
graph where connections can go all over the place and in all directions.
@ -215,11 +214,11 @@ allowed. The edges are only ever going in one direction. Like a river.
**Acyclic** means that there can be no loops in the graph. In Facebook's
graph, Alice is a friend of Bob. If Bob is a friend of Jim and Jim in turn
is a friend of Alice, this creates a loop. Like a roundabout.
In an *acyclic graph* like git uses, this is not allowed. You can create as
In an _acyclic graph_ like git uses, this is not allowed. You can create as
many relationships of edges you want. But when they re-converge, they can only
do so downstream from the direction of the graph. Like a river.
![A DAG](dag.png "Example of a graph")
![A DAG](dag.png 'Example of a graph')
So to summarize, a DAG or Directed Acyclic Graph is a graph where edges go
in one direction only (directed), and no loops are allowed (acyclic).
@ -236,7 +235,6 @@ If you can remember that, you know what a DAG is. And once you know what a DAG
is, it's easier to think about your data in git. All your changes are right
there, each version of your work represented by a node in the graph.
The question that remains is, how does git keep track of the edges, or the
relationship between the nodes?
@ -274,9 +272,8 @@ have two commits with the same ID in git. If you had two commits with the same
ID it means they are identical in every way. And so they are not two commits,
but just the same commit.
So how does it work exactly? Well, each time we *commit* data to git and create
a commit object in the process, git will make a checksum of the *commit object*
So how does it work exactly? Well, each time we _commit_ data to git and create
a commit object in the process, git will make a checksum of the _commit object_
which will end up being a node in our graph. The following data is included in
the commit object, which means it is used to calculate the checksum:
@ -301,8 +298,8 @@ one would break and so on and so forth.
In other words, all of these commits are chained together with a cryptographic
checksum that makes it impossible to tamper with them. If at this point, a
light goes off in your brain and you think *hey, haven't I heard this before
somewhere?*, then yes you most likely have heard about this sort of immutable
light goes off in your brain and you think _hey, haven't I heard this before
somewhere?_, then yes you most likely have heard about this sort of immutable
ledger because this is the exact same technology that underpins the blockchain.
At this point, I feel it's worth pointing out -- for the crypto-bros out there
@ -360,8 +357,8 @@ Initialized empty Git repository in /Users/joost/git-training/.git/
Congratulations, you have just created a **git repository**.
An empty repository for now, but a git repository nonetheless.
The English dictionary tells us that a repository is *a place where things are
stored*. In git parlor, we use the word *repository* to refer to the top-level
The English dictionary tells us that a repository is _a place where things are
stored_. In git parlor, we use the word _repository_ to refer to the top-level
folder where git is doing its magic of keeping track of our files.
In it, we can create as many files or subfolders as we like, and they are all
inside our repository.
@ -443,7 +440,7 @@ Which is why it's called `git add`. Under the hood, this data will be stored
`.git` folder. ready to be added to the DAG later.
To add data, we first need some data. So let's create a file named `hello.md`
and add a line of text in it that says *Hello git*:
and add a line of text in it that says _Hello git_:
```md title="hello.md"
Hello git
@ -465,8 +462,8 @@ nothing added to commit but untracked files present (use "git add" to track)
```
Git will still tell us that we are on branch main and that there are no
commits. But this time it will tell us that there are *untracked files*.
Specifically *hello.md*.
commits. But this time it will tell us that there are _untracked files_.
Specifically _hello.md_.
So git watches our repository and it knows there’s a file there we're not
keeping track of. It also hints us once again that we can start tracking
@ -495,7 +492,7 @@ Changes to be committed:
Hey, this is new. Git now tells us that there are changes to be committed.
It knows that there is a new file named `hello.md`.
It also tells us what command to run to *unstage* this file, which is some
It also tells us what command to run to _unstage_ this file, which is some
nice foreshadowing for the next chapter.
But before we get to that, let's take another look at the `.git` folder where
@ -539,7 +536,7 @@ At the end of the day, git is just a bunch of files on disk, and all it does
is write to those files. When git refers to our own data on disk, not its
internal metadata, but the files and folders we are looking to keep track
of, git will refer to this as the **working directory**. So when you see
that, just think *oh right, the files on my disk right now*.
that, just think _oh right, the files on my disk right now_.
At the top level we have the **index**, which is just another word for the
DAG or graph in which git keeps track of our data.
@ -549,7 +546,7 @@ prepares data before adding it to our graph.
As we saw in the previous chapter, each time we use the `git add` command,
git writes our data. Specifically, it takes the data on disk and copies
it to the staging area. It will remain there until we *commit* it. Just
it to the staging area. It will remain there until we _commit_ it. Just
like `git add` is the only way to move data from disk to the staging area,
`git commit` is the only way to move data in the staging area permanently
onto the index, which is the DAG, or git's graph.
@ -619,7 +616,7 @@ area, the next step on our learning path is the `git commit` command.
The `git commit` command is how we tell git to take the data that is in
our staging area, and add it to the DAG. To do so, git will create a
commit object and add *labels* to it. It will calculate a checksum and
commit object and add _labels_ to it. It will calculate a checksum and
add it to the commit object in the dag to link it to its parent commit.
Git will also move the `HEAD` label (remember, `HEAD` is the equivalent of
@ -630,7 +627,7 @@ the tip of the `main` branch.
But don't take my word for it, let's try it out by typing `git commit`.
When we do so, git will open an editor to allow us to write the commit
message. We'll talk about writing good commit messages later, for now let's
just write *My first commit* and then save and close the file.
just write _My first commit_ and then save and close the file.
```bash
git commit
@ -705,7 +702,7 @@ ID, you will see that it is followed by information between brackets. First it
will say `HEAD` and then a little arrow pointing to `main`.
Remember in chapter 8 where we went spelunking in the `.git` folder, we
learned that `HEAD` is like a *you are here* marker. In other words, git
learned that `HEAD` is like a _you are here_ marker. In other words, git
will put the `HEAD` label on whatever commit it considers to be where we are
right now. So each commit we make will always become a child of whatever commit
the `HEAD` label is on.
@ -817,8 +814,8 @@ the commit message. If you'd like, you can specify the commit message on the
command line with the `-m` flag, and then git will just use that.
If we now run `git status` again, git will tell us there are no changes.
It will say something like *nothing to commit, working tree clean*. And when you
hear *working tree* you should just think *working directory*. Git is telling
It will say something like _nothing to commit, working tree clean_. And when you
hear _working tree_ you should just think _working directory_. Git is telling
that the files that are in our working directory hold the exact same data as what
is stored in the DAG.
@ -888,7 +885,7 @@ we have learned so far:
Alright, so far so good. Now let's see how we can use what we've learned to
understand what git does when we start creating additional branches.
Note that we already have a branch. Everything needs to be on *some* branch,
Note that we already have a branch. Everything needs to be on _some_ branch,
so git starts us of with a default branch which is called `main`. On this
default branch, we have made two commits so far.
@ -925,7 +922,7 @@ As a practical example, imagine that you are maintaining a website. The
production code, the one that is deployed on the web server, is in the `main`
branch. Last week you've started working on a new feature: the website will
now also have a dark mode. However, you were smart, so rather than do this in
the main branch, you've created a so-called *feature branch* for this, let's
the main branch, you've created a so-called _feature branch_ for this, let's
say you've named it `dark-mode`.
Now your boss comes in and points out a small typo on the home page. It's not
@ -1088,7 +1085,7 @@ git commit -m "Manage expectations through better phrasing"
If we run `git log` again, we will see that our latest commit is added and
has both the `HEAD` and `my-feature` labels connected to it. The `main` label
meanwhile is falling further behind. Our `my-feature` branch is now two commits
*ahead* of the `main` branch.
_ahead_ of the `main` branch.
```bash
git log
@ -1119,11 +1116,10 @@ Date: Tue Apr 4 15:32:20 2023 +0200
![A branch extends](git-branch2.png)
## Chapter 20: git checkout
In the previous chapter, we used the `git switch` command to create a branch
and *switch* to it, or in other words, make it active by moving the `HEAD`
and _switch_ to it, or in other words, make it active by moving the `HEAD`
label to the tip of this branch.
We already mentioned that git only does a couple of things and the various
@ -1131,13 +1127,13 @@ commands are typically just ways to combine those different things. And the
`git switch` command is a good example to illustrate this.
As we've learned in chapter 18, we can use `git branch` to create a branch.
However, we also learned that this does not make that branch *active*. In
However, we also learned that this does not make that branch _active_. In
other words, it does not move the `HEAD` label to it. Which is why `git
switch` is handy because it does that for us.
But `git switch` is not special. All it does is combine git's basic operations
in a way that saves us some typing. In the case of creating a branch and
*switching* to it, we can accomplish the same by executing 2 commands in a
_switching_ to it, we can accomplish the same by executing 2 commands in a
row.
First, we run `git branch my-feature` to create the branch. Then we run `git
@ -1149,7 +1145,7 @@ of git's core functionalities that you should really understand.
In chapter 12, when we learned about the staging area, we learned that `git
add` adds things to the staging area, while `git commit` adds them to the
DAG or index. But so far we have only learned how to *add* data to git. The
DAG or index. But so far we have only learned how to _add_ data to git. The
question of how to get it back out hasn't come up yet.
The `git checkout` command reads data from the DAG or index and puts it on our
@ -1184,7 +1180,7 @@ git checkout main
Switched to branch 'main'
```
Git will tell us something like *Switched to branch main* which is nice of git
Git will tell us something like _Switched to branch main_ which is nice of git
and tells us that the `HEAD` label is now on the `main` branch.
But moving labels is not the only thing git has done. If you run `ls` again,
@ -1211,7 +1207,7 @@ git switch my-feature
Switched to branch 'my-feature'
```
Sure enough, git has *switched to* or activated the `my-feature` branch again
Sure enough, git has _switched to_ or activated the `my-feature` branch again
by moving the `HEAD` label to it. And if we run `ls` again, we once again
have two files, `hello.md` and `feature.md`.
@ -1234,14 +1230,18 @@ One bonus feature that `git checkout` has up its sleeve is that it can also
create branches. To do so, use the `-b` flag followed by the branch name.
So when we used
```bash
git switch -c my-feature
```
earlier to create a branch with `git switch` and it's `-c` flag for create.
We could also have ran
```bash
git checkout -b my-feature
```
instead. The result would have been exactly the same. But ultimately,
only `git branch` can create a branch. All these other commands just
re-use the same trick by calling `git branch` under the hood.
@ -1259,7 +1259,7 @@ like best. The choice is yours.
## Chapter 21: Merging in git
When we first discussed branching in git, we said that using branches is all
about *isolating our work*. And -- just to be clear on this -- this is true.
about _isolating our work_. And -- just to be clear on this -- this is true.
That's why we use branches.
However, isolation is almost always a temporary state. We don't want to isolate
@ -1268,7 +1268,7 @@ something without having to worry about any other changes. But when we're
ready for it, we'd like to come back and contribute the fruits of our labor
somehow.
In git, we call this *merging* and it is the exact opposite of *branching*.
In git, we call this _merging_ and it is the exact opposite of _branching_.
When we branch, our river splits in two. When we merge, we rejoin two
branches of our river so that they come together again.
@ -1292,7 +1292,7 @@ To merge branches in git, we use the `git merge` command.
The `git merge` command will merge whatever branch we ask it to into the branch
that has the `HEAD` label.
Remember that the `HEAD` label is the equivalent of a *you are here* marker on
Remember that the `HEAD` label is the equivalent of a _you are here_ marker on
our DAG. So if we want to merge branch `my-feature` into branch `main`, then we
should first switch to branch `main` so that the `HEAD` label is on the `main`
branch. Now if we would run the `git merge my-feature` command, git would merge
@ -1404,16 +1404,16 @@ you need to tell git explicitly that you want it to do some other type of merge.
If you just tell git to merge it will check whether a fast-forward merge is
possible, and if not will do a 3-way merge.
So that begs the question: *What is a 3-way merge?*
So that begs the question: _What is a 3-way merge?_
And arguably a more
interesting question: *Why is it called a 3-way merge?*
interesting question: _Why is it called a 3-way merge?_
It is because [with a
honey the middle there's some
leeway](https://www.youtube.com/watch?v=Pi7gwX7rjOw)?
Sadly, no. It is called a 3-way merge because git needs 3 commits to make this
merge work. The most recent commit of each of the two branches (the tip of the
branches) and a *merge commit* which is a special commit git will create and that
branches) and a _merge commit_ which is a special commit git will create and that
will have the two other commits as its ancestors.
![A 3-way merge in git](git-3way-merge.png)
@ -1446,7 +1446,7 @@ git switch main
Already on 'main'
```
Now let's add an extra line to our `hello.md` file that says *Added in main.*.
Now let's add an extra line to our `hello.md` file that says _Added in main._.
```bash
echo "
@ -1469,6 +1469,7 @@ no changes added to commit (use "git add" and/or "git commit -a")
```
But we already knew that so let's add them to the staging area with
```bash
git add hello.md
```
@ -1486,8 +1487,8 @@ on our `my-feature` branch. First, we switch to the branch with
git switch my-feature
```
Next let's add an extra line to our `feature.md` file that says *Added in
my-feature.*.
Next let's add an extra line to our `feature.md` file that says _Added in
my-feature._.
```bash
echo "
@ -1611,8 +1612,8 @@ Merge made by the 'ort' strategy.
```
Sure enough, git will prompt us for a commit message, although it's being
helpful and has already provided a default message for us saying *Merge
branch 'my-feature'*.
helpful and has already provided a default message for us saying _Merge
branch 'my-feature'_.
If we inspect the commit log with `git log` we see that we once again
have all labels in the log.
@ -1674,7 +1675,7 @@ In other words, no changes whatsoever were made to the `my-feature` branch,
the only changes -- the new merge commit -- were made on the `main` branch
because that's the one we're merging into.
Let's have a look at this *merge commit* that git created. We have its ID
Let's have a look at this _merge commit_ that git created. We have its ID
right there in the log, so we can use `git show` to show it in detail.
```bash
@ -1697,7 +1698,6 @@ the merge, the most recent commits on each of the merged branches.
In other words, these IDs together with the merge commit itself, make up the
3 commits that together form a 3-way commit.
Some people -- let's call them git purists -- do not like this kind of empty
merge commit. Which is why git also provides different ways to merge things.
@ -1710,9 +1710,9 @@ new commits from one branch into another, git will instead take this bunch of
new commits, and stage them as a single ready-to-go commit that will have the
same effect.
It is essentially telling git *Hey git, I did a bunch of work here in this branch,
It is essentially telling git _Hey git, I did a bunch of work here in this branch,
now can we pretend I did all of that in one sitting and just make it a single
commit as if there was never a branch at all*.
commit as if there was never a branch at all_.
An example will make this more clear, but before doing so, let me quickly go
back to the point before our merge. Yes, you can do that. No I won't show you
@ -1876,7 +1876,7 @@ In this chapter, we are going to look at how git can help us compare different
versions of our files.
The way to do that is with the `git diff` command -- which you should write with
double `f` because it stands for *difference*. By default, the command will
double `f` because it stands for _difference_. By default, the command will
compare your working directory -- that is the files on your file system right
now -- with the staging area.
@ -1895,7 +1895,7 @@ So let's quickly make a change by opening the `feature.md` file and change
the `This is extra commit 2.` line to `This is extra commit 3.`.
If now we run `git status` git will tell us that there are changes in
`feature.md` that have not been staged. Ok, good to know. But what *exactly*
`feature.md` that have not been staged. Ok, good to know. But what _exactly_
has changed? If we run `git diff` git will tell us.
```bash
@ -1986,7 +1986,7 @@ want to share our changes with them.
Fueled by the rise of git hosting sites like
[GitHub](https://github.com) and [GitLab](https://gitlab.com/)
this scenario has become so popular that today many people don't fully
comprehend the difference between let's say *git* and *github*.
comprehend the difference between let's say _git_ and _github_.
Not you of course. You're on chapter 27 and are probably eager to find out
how we get git to talk to the network.
@ -2013,9 +2013,9 @@ Let's look at each of these in detail over the next 4 chapters.
If you've ever used git before, chances are `git clone` was the very first
command you used. That is because unlike `git init` which creates a repository
locally, `git clone` will set up a local copy of a pre-existing repository
that exists *somewhere else*.
that exists _somewhere else_.
This *somewhere else* can be many different things. It can be another folder
This _somewhere else_ can be many different things. It can be another folder
on your computer, a shared drive, or network mount, a remote location that
you access over SSH or another tunnel, or the most common scenario, a
git hosting service like GitHub or GitLab.
@ -2120,7 +2120,7 @@ origin git@github.com:joostdecock/git-training.git (push)
```
We can see that git has not one but 2 URLs for our origin.
One to **fetch** and one to **push**. So let's look at what *fetch* is all
One to **fetch** and one to **push**. So let's look at what _fetch_ is all
about in the next chapter.
## Chapter 29: git fetch
@ -2319,7 +2319,7 @@ Date: Wed Apr 5 18:33:55 2023 +0200
```
However, and this is a bit embarrassing. For the commit message I wrote
*My firts commit* when it should have been *My first commit*.
_My firts commit_ when it should have been _My first commit_.
This is not that big a deal perhaps, but I don't want my first commit to
forever be plagued by a typo in the commit message. But, I can amend it
@ -2362,8 +2362,8 @@ Important enough to warrant its own chapter.
## Chapter 33: A warning about rewriting history
In the previous chapter, we got our first taste of how we can *rewrite
history* in git. In the next chapters, we'll see more ways that we can go back
In the previous chapter, we got our first taste of how we can _rewrite
history_ in git. In the next chapters, we'll see more ways that we can go back
and make changes to the DAG, the structured data where git keeps all our work.
However, there's an important caveat that you should keep in mind whenever you
@ -2446,7 +2446,7 @@ no changes added to commit (use "git add" and/or "git commit -a")
But the use of `git reset` is not limited to clearing out the staging area.
You can also reset an earlier state of the DAG. Either by referencing a
specific commit or -- as it's used rather often -- by telling it how many
steps to *go back* from `HEAD`.
steps to _go back_ from `HEAD`.
This should be easier to understand when we use an example. Let' say you are
working on solving a bug. You've created a branch for this, and you've finally
@ -2550,14 +2550,14 @@ Date: Wed Apr 5 18:33:55 2023 +0200
```
You probably noticed that I used the `--soft` flag after the `git reset`
command. Which begs the question *what is a soft reset, and is there also a hard
reset?*. The answer is yes. Let's look at the various types of resets in the
command. Which begs the question _what is a soft reset, and is there also a hard
reset?_. The answer is yes. Let's look at the various types of resets in the
next chapter.
## Chapter 35: Soft, mixed, and hard resets in git
The default mode of `git reset` is to do a so-called *mixed* reset, which
personally I think should be called *firm* reset because it's in
The default mode of `git reset` is to do a so-called _mixed_ reset, which
personally I think should be called _firm_ reset because it's in
between a soft and a hard reset.
A soft reset will reset changes from the DAG but will leave them in the
@ -2578,7 +2578,7 @@ re-commit them again, you are simply bundling some commits into one.
You should use a `--mixed` reset -- which is the default, so you don't have
to specify it -- if you want the commits undone and also
removed from the staging area. Perhaps you made some changes that in
retrospect were not a good idea. Typically this means you want to *undo*
retrospect were not a good idea. Typically this means you want to _undo_
commits entirely.
You should only ever use a `--hard` reset if you know what you are doing,
@ -2588,7 +2588,7 @@ you are not afraid of losing your work, or you learn best by suffering.
By now we've learned how git uses labels to reference specific commits.
We've also learned that the `HEAD` label is special because it acts like a
*you are here* marker on our DAG telling us where we are at any moment.
_you are here_ marker on our DAG telling us where we are at any moment.
But git also creates labels for each branch, and even adds labels for
remote branches.
@ -2599,7 +2599,7 @@ Such a tag is a label created by you rather than one that git manages
internally. It also will never move, unlike the way git automatically
moves its internal labels to keep track of things.
Tagging commits like this is a way to sort of *bookmark* a commit so you can
Tagging commits like this is a way to sort of _bookmark_ a commit so you can
refer to it in a simpler way than by using its checksum ID. One use case
where tagging is used extensively is to track releases throughout the
lifecycle of a project.
@ -2630,9 +2630,9 @@ the state it was when version 1.1.0 came out by running `git checkout v1.1.0`.
If you do so right away, nothing special will happen. But if you do it further
down the line when more commits have been added you will find that git freaks
out a bit because you are now in a *detached HEAD* state.
out a bit because you are now in a _detached HEAD_ state.
We will cover what exactly such a *detached HEAD* state is in a later chapter.
We will cover what exactly such a _detached HEAD_ state is in a later chapter.
For now, let's just agree that it sounds equal parts scary and funny.
## Chapter 37: git stash
@ -2672,7 +2672,7 @@ command, git will essentially add your changes to a commit object. But it
won't actually commit anything, but instead push this commit object on the
stash stack.
After doing this, it will ensure that your working directory is *clean* again,
After doing this, it will ensure that your working directory is _clean_ again,
in other works in sync with `HEAD`.
If, at any moment, potentially after `HEAD` points to a new commit, you
@ -2714,7 +2714,7 @@ But sometimes, that's not what you want. You typically want to keep track of
only those files that matter, and not things like dependencies, build
artifacts, error logs, or those pesky `.DS_Store` files on mac.
Fortunately, git has a standard way to tell it to *ignore* certain files
Fortunately, git has a standard way to tell it to _ignore_ certain files
or folders and that is through a `.gitignore` file.
A `.gitignore` file is typically added to the top-level folder of a repository
although it's worth pointing out that you can also add one in a subfolder.
@ -2773,14 +2773,14 @@ Or you can create a branch where you are right now, which will mean `HEAD`
will now be on the tip of your newly created branch and thus will also no
longer be detached.
Whichever option you choose, a *detached HEAD* state is not a good place to
Whichever option you choose, a _detached HEAD_ state is not a good place to
make changes. So if you want to just have a look around without changing
anything, that's fine. But if you plan to add commits, you should really
start by creating a branch first.
## Chapter 40: References in git
A *reference* in git is an umbrella term for anything that points to a given
A _reference_ in git is an umbrella term for anything that points to a given
commit in the DAG.
A reference can be a commit ID, a label or tag like `HEAD`, a branch name,
@ -2800,7 +2800,7 @@ We've talked about the DAG in git, and how various commits are linked together.
But we have not really delved into how git keeps track of things under the
hood. In other words, how is all this information stored in the `.git` folder.
Git provides a *content-addressable filesystem*. Which is a fancy word to throw
Git provides a _content-addressable filesystem_. Which is a fancy word to throw
around, but really just means that git acts as a big key-value store. You give
it something to store, and it will hand you back a key to retrieve it with.
This key is, of course, the checksum that we've mentioned earlier.
@ -2813,7 +2813,7 @@ The same is true here. The way commits are stored is not unique to commits.
Git has 4 types of objects that it stores, and commits are only one of them.
So called **blob-objects** are what store your actual data. If you add a file to
git, the contents of that file will go in a *blob-object*. You give it the
git, the contents of that file will go in a _blob-object_. You give it the
file contents, you get an ID in return. Done.
This has the nice side effect that no two identical files will ever be stored
in git. Let's say you keep your documentation in git -- which would be a smart
@ -2827,18 +2827,18 @@ Another object type in git are called **tree-objects**. A tree object addresses
some shortcomings of the blob-objects. For example, we need to be able to
store the filename somehow. Which is different from the file contents. And if
we add a bunch of files together, we need to keep track that these files belong
together. This sort of information is stored in *tree-objects* in git.
together. This sort of information is stored in _tree-objects_ in git.
Then, there are the **commit-objects**. These are, of course, the objects we've
been paying most attention to so far. In chapter 6 we explained that a commit
object holds the data itself, the author, the date, the log message, and the
checksum of the parent commit.
Well, when we wrote *the commit data itself* what that means under the hood is
the ID of the *tree-object* that holds the information about the data stored for
Well, when we wrote _the commit data itself_ what that means under the hood is
the ID of the _tree-object_ that holds the information about the data stored for
this commit.
The last type of object that git uses are for *annotated tags*. We've seen
The last type of object that git uses are for _annotated tags_. We've seen
before how you can attach your own label to any commit with the `git tag`
command. What we didn't get into is that you can add more info to the tag
such as a message or you can even cryptographically sign a tag. Git needs
@ -2853,7 +2853,7 @@ strong feelings on the matter, others see the commit messages as a nuisance
and put in whatever just to make git happy.
There have been efforts to create rules for commit messages that people should
adhere to, such as the *Conventional Commits* specification which you can read
adhere to, such as the _Conventional Commits_ specification which you can read
about at [conventionalcommits.org](https://www.conventionalcommits.org/). But
at the end of the day, how you write your commit messages depends a lot on
context. Is it a project you work on alone, or do you work together with
@ -2883,7 +2883,7 @@ from line 3.
## Chapter 43: Dealing with merge conflicts
While the *detached HEAD* state you might find yourself in may sound scary,
While the _detached HEAD_ state you might find yourself in may sound scary,
the situation that most git users would like to avoid is having to deal with
a merge conflict.
@ -2907,23 +2907,31 @@ For this scenario, we are going to create a new git repository (with `git init`)
and quickly create a merge conflict by:
- Adding and committing a `conflict.md` file that holds:
```md title="confict.md"
I will cause murge conflict
I will not
```
- Creating a new branch named `notmain`
- On the `notmain` branch, update the `conflict.md` file so that it holds:
```md title="confict.md"
I will cause a merge conflict
I will not
```
and then add and commit that change.
- On the `main` branch, update the `conflict.md` file so that it holds:
```md title="confict.md"
I will cause merge conflict
I will not
```
and then add and commit that change too.
- Finally, we switch to the `main` branch and attempt to merge with the `git
merge notmain` command.
@ -2936,7 +2944,7 @@ CONFLICT (content): Merge conflict in conflict.md
Automatic merge failed; fix conflicts and then commit the result.
```
Git is asking us to *fix conflicts and then commit the result*.
Git is asking us to _fix conflicts and then commit the result_.
If we run `git status` at this point, it will also say that there is a merge
conflict and ask us to either fix the conflict and then run `git commit` or
abort the merge with `git merge --abort`.
@ -3027,8 +3035,9 @@ were before. This time around, let's look into the contents of `conflict.md`:
I will cause merge conflict
=======
I will cause a merge conflict
> > > > > > > notmain
I will not
> > > > > > > I will not
```
If you do this, you will see that git has included the changes from both
@ -3084,7 +3093,7 @@ enjoyable, but also facilitate working with others.
- Branches are free. Use them.
- Make many small commits, rather than 1 massive commit.
- Adding things to the staging area is a good way to do a *soft-save*
- Adding things to the staging area is a good way to do a _soft-save_
before you're ready to commit.
- Write commit messages that focus on why you did something, not what you did.
- Update your prompt to show what branch you are on. You can [download a script
@ -3109,8 +3118,7 @@ Thankfully, git has a ton of inline documentation, and there's a wealth of
information out there on the internet for when you want to learn about the more
advanced corners of git.
There's also a bunch of GUI tools that can help you visualize the git DAG such
as [gitx](https://github.com/gitx/gitx/releases) or [gitkraken](
https://www.gitkraken.com/jc).
as [gitx](https://github.com/gitx/gitx/releases) or [gitkraken](https://www.gitkraken.com/jc).
My goal throughout this series was not to provide you with the ultimate git
training. Instead, I wanted to show you that when it comes to git, there's