Git newb's Corner

How to set up a git repo on a local computer. A guide for newbs.

This guide is written for newbs to git, written by a newb to git. It outlines the basic steps for setting up a repository of your org files on a computer on your LAN. This is an alternative to using a cloud service like dropbox. You will be able to sync your files anytime you are connected to the LAN. The guide also shows how to set up a local computer so it can sync with the repo, to allow editing org files there too.

As it is now, the guide uses commands used in Debian GNU/Linux. Presumably the method in other distros is not different, even if the syntax is.

For the purposes of this guide, assume the repository will be stored in a directory called ~/org-repo.

Install git.

On the computer where the repo will be stored, install git if it isn’t there already. Use the package manager, or open a terminal emulator and type:

sudo apt-get install git-all

For installing on non-Debian-based OSes, see https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

Create the git repository.

On the machine on which you want to keep the repository, create the directory in which you want to keep the repo:

mkdir ~/org-repo 

Go into the directory you just created and tell git you want a repo here:

cd ~/org-repo
git init

The directory should now contain a subdirectory called .git containing items with names like HEAD, branches, config,… You can check using this command:

ls .git

Copy your org files to the repo.

Assuming your files are in ~/org,

cp ~/org/*.org ~/org-repo

Make git aware of the files you want to belong to the repo:

git add *.org

Make the files part of the repository:

git commit *.org  -m 'Initial commit'

Git requires you write a message whenever you commit. If you don’t use the -m option to leave your message you will be sent to your default editor to write the message there.

Make the repository a “bare tree”. You have to do this. Maybe someone can explain why.

git config --bool core.bare true

Now you have a git repository for your org files! This is not where you will edit them. You will edit your files on SyncOrg or in other directories that contain their own copies of the repository.

How to create a local copy of your repo so you can edit the files on a computer

As good as SyncOrg is, you may find from time to time that want to edit your org files on a full-size keyboard. Since you can’t edit files directly in ~/org-repo, you have to make a local copy of the repo. There you will first sync the files, then edit the files, then send your changes to ~/org-repo. Here’s how to do that.

The natural place to edit your org files is ~/org of course, and that’s what’s described below, but you can do this in any directory you like. Git is going to require that we remove all files from ~/org before we start, so if you already have an org directory, now might be a good time to back up your files. Theoretically, we already made a backup in ~/org-repo, but you know what happens when you believe things that are theoretically true are actually true.

If it doesn’t already exist, create ~/org.

mkdir ~/org

If it does already exist, delete all files and subdirectories from ~/org. This command will delete everything in ~/org, including hidden files.

find ~/org  -mindepth 1 -delete

Obviously, use with caution.

Make a local copy of the repo. If you are setting this up on the same computer where ~/org-repo is stored, all you need to do is

cd ~/org
git clone ~/org-repo ~/org

What if you want to edit your files on a different computer, though? Maybe ~/org-repo is on your NAS and you want to edit on your laptop? It’s almost as easy. Let’s say ~/org-repo is set up on 192.168.1.100 under the user FHulot:

git clone ssh://[email protected]:/home/FHulot/org-repo ~/org

If you have not set up SSH keys, you may have to enter a password. For a tutorial on setting up keys for SSH, try https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2

You’ve done it! Now you have copies of all your files locally and can edit to your heart’s content!

How to make changes to the local repo and then send them to the main repo.

Before you edit files in the local repo, you need to make sure they are up-to-date with the main repo:

git pull

If you have not set up SSH keys, you may have to enter a password. For a tutorial on setting up keys for SSH, try https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys–2

When you have made changes and are ready to send them to the main repo, first commit the changes to your local repo:

git commit -a -m 'your reason for changing'

The -a option tells git to commit any repo files that have been modified. If you prefer, you can give a list of files to commit:

git commit project1.org project5.org day*.org -m 'your reason for changing'

Now send the changes to the main repo:

git push

Now your changes are available to SyncOrg! And any other local computer set up to sync with ~/org-repo.

Setting up SyncOrg to work with your repo.

Again, assume ~/org-repo is set up on 192.168.1.100 under the user FHulot. Using the setup wizard in SyncOrg, the relevant entries are:

• I want to sync using: an SSH server
• USERNAME: FHulot
• AUTHENTICATION: your choice of password or key
• PATH: /home/FHulot/org-repo
• HOST: 192.168.1.100
• PORT: 22