Git Repositories and Workflows on elementary OS

A practical way to learn how to set up a Git repository and workflow on elementary OS is to build a small text-based project and give it a deliberate history. Git is the version-control engine: it records snapshots, compares changes, and helps move an idea through a controlled review process.

That distinction matters on a friendly desktop such as elementary OS, where people may arrive from graphical applications without knowing that Terminal, Git and a text editor form one connected toolchain. You do not need a development team or a paid service to begin. A project folder, a useful README and a few consistent commands provide a solid starting point.

This guide follows the path from installation to commits, branches, remotes and backups, with commands suitable for the Ubuntu-based packages used by current elementary OS releases. The same habits work with GitHub, GitLab, Bitbucket, Gitea or a repository that never leaves your computer. Replace the sample identity and project names with your own, and keep credentials out of tracked files.

Install Git and establish your identity

Open Terminal from the Applications menu and install Git through the distribution package manager. This avoids an unfamiliar downloaded binary and fits the way elementary OS normally receives updates.

sudo apt update
sudo apt install git
git --version

The version number confirms that Git is ready. On a current elementary OS release, the package should be recent enough to support modern commands such as git switch, git restore and branches created with git init -b.

Before making a commit, tell Git who you are. These values are attached to your commits and are stored in ~/.gitconfig.

git config --global user.name "Alex Morgan"
git config --global user.email "alex@example.com"

Use the name and email you want other contributors to see. If you contribute to public projects, a personal address may be appropriate; for private work, use your organisation’s address if that matches your working preferences.

Keep separate identities when necessary by overriding the global settings inside an individual repository.

cd ~/Projects/aurora-notes
git config user.name "Alex Morgan"
git config user.email "alex.morgan@example.com"

Configure a consistent branch name and a straightforward editor, then inspect the resulting settings.

git config --global init.defaultBranch main
git config --global core.editor "nano"
git config --global --list

Using main as the initial branch makes local repositories and hosted services easier to compare. Review the configuration whenever you are unsure which identity, editor or remote a command will use.

Create the repository and record its first commit

A repository is a project directory with a hidden .git folder containing its history. Create a descriptive folder, enter it and initialise Git.

mkdir -p ~/Projects/aurora-notes
cd ~/Projects/aurora-notes
git init
git status

The status command should describe an empty working tree. Before committing anything, create a README.md that explains the project’s purpose, how it is used and any licence or compatibility information. Use Australian spelling where it suits the project, and write dates as DD/MM/YYYY in prose so they remain clear to local readers.

A .gitignore prevents unsuitable files from being added accidentally.

nano .gitignore

# Editor leftovers
*~
*.swp

# Local configuration and secrets
.env
*.pem

For wider reading on development practice, the notes at Laguna de Contreras can accompany the documentation you build. In your own repository, track the ignore rules before they are needed, and review every proposed addition rather than staging the entire directory with an indiscriminate command.

Stage specific files, inspect the pending changes and create a commit with a message that explains the purpose of the update.

git add README.md .gitignore
git status
git diff --staged
git commit -m "Add project overview and ignore rules"

The staging area lets you separate changes into deliberate groups. If a file was added by mistake, remove it from the pending set with git restore --staged filename; this leaves the file in place without deleting your work. After committing, git log --oneline --decorate provides a compact history of the project.

Work with branches, reviews, and recovery

A branch is an independent line of development attached to the same repository. Use branches for individual features, corrections or experiments instead of placing unfinished work directly on main.

git switch -c feature/backup-restore
mkdir -p docs
printf '%s\n' '# Backup and restore' 'Record the backup steps here.' > docs/backup.md
git add docs/backup.md
git commit -m "Document the backup procedure"

Switch back to the stable branch when the feature is ready, then integrate it after testing.

git switch main
git merge feature/backup-restore
git log --oneline --graph --decorate --all

Merging combines the branches while retaining their commit history. Rebasing replays your commits on top of another branch and can produce a tidier local history, but it rewrites commit identifiers. Rebase branches that only you use; avoid rewriting commits that other people have already pulled.

Git records commit timestamps as Unix time with a UTC offset, while the displayed time follows your system’s time zone. Australian users should use the correct IANA identifiers rather than a fixed offset. Melbourne, Sydney, Canberra and Hobart observe daylight saving; Brisbane does not; Adelaide uses a half-hour offset; and Perth sits eight hours ahead of UTC. A fixed offset will therefore produce incorrect timestamps during part of the year.

After adding a remote, publish a feature branch and use the hosting service’s review process.

git push -u origin feature/backup-restore

GitHub and Bitbucket call this a pull request; GitLab calls it a merge request. Ask a colleague to inspect the changes, run the project and approve the update before merging into a protected main branch. Small commits with clear messages are easier to review than one large update covering unrelated work.

Before storing sensitive material in a project, keep credentials in a password manager or the system keyring rather than in tracked configuration files. The site’s AppArmor and SELinux basics explains how application confinement adds another layer of workstation protection. These mechanisms do not replace Git file permissions, SSH keys or careful handling of secrets.

Compare hosting models and connect a remote

A remote is a named connection to another copy of the repository. The default name is usually origin, although a project can have several remotes. SSH authentication is convenient because the hosting service receives a public key rather than a reusable password.

ssh-keygen -t ed25519 -C "alex@example.com"
cat ~/.ssh/id_ed25519.pub

Add the displayed public key to the SSH settings in your hosting account. Keep the private id_ed25519 file outside the repository and protect it with a passphrase. An SSH agent can hold the key for the current session without repeatedly requesting that passphrase.

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Once the account accepts the key, connect the local repository to the empty remote repository.

git remote add origin git@your-host:your-user/aurora-notes.git
git remote -v
git push -u origin main

Replace your-host with the provider’s SSH hostname and your-user with your account name. The push establishes the upstream relationship, so later branch commands can use git push and git pull without repeating the remote name. Hosted platforms also support token-based HTTPS connections, but SSH avoids embedding a reusable token directly in the remote address.

Australia’s technology sector has strong Git communities in Sydney, Melbourne, Brisbane and Canberra. Atlassian, the Sydney-based company behind Bitbucket, helped popularise hosted Git, while many Australian teams use GitHub or GitLab and some community organisations operate their own Gitea instances. Provider differences matter less than knowing where the code, backups, billing accounts and account-recovery details are held.

For Australian budgets, check whether private hosting is billed in AUD and whether GST applies to a purchase. A self-hosted service on an Australian virtual server may simplify contracts and latency, but it transfers patching, monitoring and backup responsibilities to you. NBN and mobile connections can be uneven outside major cities, so teams in Melbourne, Brisbane, Perth or regional Australia should retain a local clone and test that backups can actually be restored.

Approach	Best suited to	Setup effort	Main advantages	Main trade-offs
Local Git repository	Private notes, scripts and experiments	Low	Works offline, no account required, simple copies	No shared review tools; backups and publishing are manual
Hosted Git service	Public projects and collaborative teams	Low	Pull requests, issues, access controls and easy invitations	Internet dependency; check account recovery, pricing and data policies
Self-hosted Gitea or GitLab	Organisations with server capacity	High	Server location and policies remain under your control	Maintenance, monitoring, security and backups become your responsibility

Make the workflow repeatable

Turn the sequence into a routine: begin with git status, update the stable branch only when the working tree is clean, create a branch for the task, make focused commits, test the result and merge only after review. Use git diff to inspect unstaged changes and git log --oneline --graph to understand how the branches fit together. Keep personal and work identities separate with repository-level configuration. If a credential has entered published history, rotate it immediately; rewriting old commits does not erase existing clones.

Back up both the working files and the .git directory. An offline bundle preserves committed history and can be copied to another drive.

git bundle create ~/Backups/aurora-notes.bundle --all

Test that the bundle can be cloned, keep another copy offline, and remember that uncommitted working-tree changes are not included in the bundle. Open Terminal now, create ~/Projects/aurora-notes, run git init, write a one-line README.md, and make that first commit.