March 27, 2023

Start using git to keep track of file versioning

This is a quick guide to start using git. I would like to help other writers use git, a version control tool.

I use git to keep track of my writings. I write texts, essays, etc.

Table of contents

1. Why would you want to use git as a writer?
2. Getting started using git: create a git repository, make changes to a file and merge your changes into master
3. Other git commands you might find useful

Why would you want to use git as a writer?

As a sole writer:

• stop duplicating files to keep track of modifications e.g. chapter_version_1.txt, chapter_version_yesterday.txt, etc.
• do not hesitate to delete text; everything you commit (I will define later) can be retrieved. Delete with confidence, recover if needed.
• edits, reoganise, et cetera text without altering “the main” copy

As writers collaborating:

• no more duplicates e.g., doc_alice_edits.txt, doc_bob_edits.txt, doc_john_edits.txt
• no more waiting for other to send you the lastest version or whatever
• use git to check for “conflicts” (differences) when two or more persons have worked on same file
• each writer can use their own text editor, their own system to write. Git is agnostic.

There are many more reasons. This is just to give the reader of this blog post an idea of why a writer would want to use git. The point of this blog post is the example below.

Getting started using git: create a git repository, make changes to a file and merge your changes into master

In this example we will learn how to use git to keep track of revisions of a text file: file.txt. We will:

• create a git repository in a directory
• initiate tracking for a file
• create a branch
• edit a file without altering “the original” copy
• commit (save) that change
• merge the change with “the original” file
• delete the branch to leave the repository clean

You should be familiar with using the command-line interface (i.e. the terminal, the shell). You can find more information on learning to the use the command line there: https://yctct.com/cli.

If you need to install git on Trisquel GNU/Linux run:

$ sudo apt install git

Start by creating a directory (a folder) named book where we will create and keep track of a file:

$ mkdir book

Move into the directory book:

$ cd book

Create a file:

$ touch file.txt

Initiate a git repository in this directory:

$ git init

The shell (a.k.a the terminal) should print:

Initialized empty Git repository in /home/user/book/.git/

We can check the status of our repository:

$ git status

The shell should print:

On branch master

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    file.txt

nothing added to commit but untracked files present (use "git add" to track)

Git tells us that it can see file.txt but does not track it (yet).

As suggested by git in the message above, to start tracking file.txt we run:

$ git add file.txt

We can run git status to check that file.txt is tracked by git. The shell should print:

On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
    new file:   file.txt

file.txt is now tracked but not recorded to the repository yet. To record a file to the repository we need to commit (save, in a way) that file. To commit file.txt we run:

$ git commit -m "Add file"

-m stands for “message”; a message appended to the commit. You can run $ man git-commit to learn more about commits.

The shell unexpectingly prints:

*** Please tell me who you are.

Run

  git config --global user.email "you@example.com"
  git config --global user.name "Your Name"

to set your account's default identity.
Omit --global to set the identity only in this repository.

fatal: unable to auto-detect email address (got 'yourusername@computer.(none)')

Our commit did not go through. The repository does not know who we are. When we will collaborate with others on the same repository, and commit changes, git will need to know who commits come from.

We follow the above instruction to set the identity of our account, we run:

$ git config --global user.email "alice@yctct.com"
$ git config --global user.name "Alice A"

N.B. #1: do not forget to substitute the placeholders for your email address and name.

N.B. #2: This email address and name will show up in the commits for others to see.

Now that we created a repository, added file.txt and set our identity, we can commit file.txt to the repository (try Crtl+P to retrieve commands you’ve previously typed in the shell):

$ git commit -m "Add file"

The shell should print:

[master (root-commit) 954ea14] Add file
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 file.txt

We run git status to check where we are at. The shell should print:

On branch master
nothing to commit, working tree clean

Good.

We can also run git log to print our commit to the shell:

commit 954ea14e97ff2f2f690583bdb728d3fdab584376 (HEAD -> master)
Author: Alice A <alice@yctct.com>
Date:   Sun Mar 26 12:32:31 2023 +0100

    Add file

That is the commit we just made. You can see that our change was committed to the branch master.

Now we want to start working on file.txt. In this example, we will add a title. That is not much but the process will be the same for any future work you will want to keep track of.

The first thing we want to do before make any modification to our file is to create a branch (a sort of copy) of the directory where the reposiroty lives. We do not need to create copy of file.txt e.g. file_version1.txt!

We create a branch named add-title:

$ git branch add-title

(You can run $ man git-branch to learn more about branching.)

We can check that the branch was created by running:

$ git branch

The shell should print:

  add-title
* master

We can see that the branch add-title was created.

We can also see that we are still on the branch master. The * indicates which branch we are on.

We want to add a title to file.txt so let’s switch to the branch add-title where we will be able to make changes to file.txt without altering file.txt on the branch master.

To switch to the branch add-title we run:

$ git switch add-title

We can check that we switched to the branch add-title by running:

$ git branch

The shell should print:

* add-title
  master

The * indicates that we are on the branch add-title.

Now we can start editing file.txt.

We can add a title to file.txt (using the programme echo) and check that the title was added (using the programme cat):

$ echo "# This is a title" > file.txt
$ cat file.txt 
# This is a title

Good. cat prints the content of file.txt to the shell.

Now we run git status to check where we are at.

The shell should print:

On branch add-title
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   file.txt

no changes added to commit (use "git add" and/or "git commit -a")

We are happy with the title we added to file.txt so we commit the modification.

First: we stage (that is, add) the file to the staging area by running:

$ git add file.txt

N.B.: you will make use of the staging area in the future. For now it makes no different. Just an extra step we have to take.

We can run git status to check that file.txt was staged. The shell should print:

On branch add-title
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified:   file.txt

Now we commit:

$ git commit -m "Add title"

The shell should print:

[add-title bc4803f] Add title
 1 file changed, 1 insertion(+)

We can run git log to prints our commits to the shell:

commit bc4803f1330c1febeaee3283ee858be079bd3665 (HEAD -> add-title)
Author: Alice A <alice@yctct.com>
Date:   Sun Mar 26 12:58:18 2023 +0100

    Add title

commit 954ea14e97ff2f2f690583bdb728d3fdab584376 (master)
Author: Alice A <alice@yctct.com>
Date:   Sun Mar 26 12:32:31 2023 +0100

    Add file

Those are the two commits we made so far: first adding file.txt to the repository, and then adding a title to file.txt. We can see that the first commit was made on the branch master and the second (the one at the top) to the branch add-title.

We can also run git status to check that the branch is “clean”, that file.txt was committed:

On branch add-title
nothing to commit, working tree clean

If we are happy with the modification we have just made i.e. adding a title, we can merge the changes into to branch master and delete the branch add-title.

First we switch back to the branch master:

$ git switch master

N.B.: we need to commit all changes to switch branch.

The shell should print:

Switched to branch 'master'

To see that changes made on the branch add-title did not affect the branch master we can print the content of file.txt:

$ cat file.txt

The shell should print nothing. (file.txt has no title on the branch master.)

We can check that the branch add-title was not merged yet:

$ git branch --no-merged

The shell should print branches that are not merged, in our case the branch add-title:

add-title

To merge changes made on the branch add-title into the branch master we run:

$ git merge add-title 

(You can run $ man git-merge to learn more about merges.)

The shell should print:

Updating 954ea14..bc4803f
Fast-forward
 file.txt | 1 +
 1 file changed, 1 insertion(+)

We can check that changes of the branch add-title were merged onto the branch master:

$ git branch --merged

The shell should print branches that are merged (and indicates which branch we are on):

  add-title
* master

We can also check that file.txt was modified, again using the programme cat:

$ cat file.txt 
# This is a title
    

Now we can delete the branch add-title since its changes were merged into the branch master, we run:

$ git branch -d add-title 

The shell should print:

Deleted branch add-title (was bc4803f).

We can run git status to check the status of our repository. The shell should print:

On branch master
nothing to commit, working tree clean

We are done learning the very basics of git. We:

• created a repository in a directory with file.txt
• set the identity of our git account
• created a branch
• made a change to file.txt
• committed that changes to the newly created branch
• merged the changes into the branch master
• deleted the branch where we worked to keep the repository clean

I hope you can now use git to track versioning of your work. If not, you can run $ man git to learn more or drop me a line via email. I would be happy to help further by writing another blog post for example. Let me know.

Other git commands you might find useful

$ git diff

shows changes between commits in the shell.

$ git add . 

stages all files. Also useful when you stage one single file so you don’t have to type the name of the file.

$ git ci --amend --no-edit

adds changes to the last commit. In other words, it is useful if you already committed and forgot to add something to a file (do not do if you already pushed, for those who use git to collaborate). You can commit a change without adding a new commit.

$ git ci --amend 

same as above, but prompts you to also update the message of the commit.

$ git ci -am "Commit message"

stages (add) and commit at once. No need to run git add .

$ git branch -v

lists the last commit on each branch.

You might also want git to ignore .pdf files so they don’t show up when you run git status. To do so you can tell the .gitignore file to ignore files with extension .pdf. In the directory run:

$ echo "*.pdf" > .gitignore

to check that *.pdf was written to the hidden file .gitignore you can run:

$ cat .gitignore

which should print:

*.pdf

One more thing if you are unfamiliar with hidden files: to list hidden files run $ ls -a.

learn personal computing command-line interface (cli) git start using wiki office applications text processing shell literacy