Keep a history of your work
Imagine working on a website with a friend. You want to try a new homepage, keep the current one working, and understand what your friend changed. Copies named website-final and website-final-2 soon become difficult to manage.
Git is a version-control tool: it records chosen versions of your files and helps combine work from different people. You can inspect an earlier version, find the change that introduced a problem, and explain why a change was made. It is useful for code, documentation and other files that change over time.
Where Pillion fits
Git runs on your computer. Pillion keeps a shared copy of your Git repository online and gives you a website for discussing and reviewing the work. This kind of service is sometimes called a Git forge.
On your computer
Edit files in your usual editor. Use Git to inspect changes and record versions. You can do this without an internet connection.
On Pillion
Share recorded versions, read files in your browser, ask for feedback, track tasks and run automated checks.
Your local copy and the copy on Pillion do not synchronise automatically. You decide when to send your commits with push and bring other people’s changes back with pull.
A repository holds files and their history
A repository, often shortened to repo, holds a set of files and the history Git records for them. On your computer it looks like an ordinary folder, with a hidden .git directory containing Git’s records.
A repository on Pillion has an owner and a name, such as sam/hello-pillion. The owner is a person or an organization. Cloning downloads a local copy of the repository and its history so you can work on it.
Your clone remembers the address it came from under a short name called a remote. Git normally calls that remote origin. Commands such as git push origin main use that saved address.
Saving a file, committing and pushing
These are separate steps. Suppose you update a paragraph in README.md, the introductory document for a repository:
| Step | What it does | Where it lives |
|---|---|---|
| Save | Your editor writes the edited file to disk. | Your computer |
| Stage | git add README.md selects that version of the file for your next commit. | Your computer |
| Commit | git commit records the staged changes as a point in the history with a message. | Your computer |
| Push | git push sends your commits to a remote repository. | Pillion, after the push succeeds |
A commit records a snapshot, its author and a message explaining the change. It also has an identifier, often shown as a short sequence such as a1b2c3d. Make small commits that describe one coherent change; they are easier to review and understand later.
A saved file is not yet a commit. A commit is not yet on Pillion. Until you push successfully, that work is only in your local copy.
If you edit a file again after staging it, stage it again to include the latest edits. Git does not automatically add those later edits to the next commit.
Branches let you work on a change separately
A branch is a named line of work in the same repository. A repository often uses main as its default branch: the shared starting point for new changes. A branch such as improve-readme lets you make commits without immediately changing main.
Switching branches updates the files in your folder to that branch’s version. A branch does not create another folder. Commit your current work before switching so that you know where it belongs.
A merge combines changes from one branch into another. Git can often combine them automatically. When two changes overlap and need a human decision, Git reports a merge conflict.
Use Pillion to discuss the change
A pull request asks to merge one branch into another. On Pillion, it brings the proposed changes, discussion and checks together before the merge. Reviewers read a diff: a comparison showing added and removed lines.
An issue tracks a question, bug or task. For example, an issue might say “Explain how to run the website”; a pull request might contain the README change that addresses it.
Despite their similar names, git pull and a pull request do different jobs. The command updates your local branch from a remote; the pull request is a discussion and proposal to merge on Pillion.
Try it with a small repository
You do not need an existing coding project to learn this. In Your first repository, you will create a text file, record it with Git, share it on Pillion and make a change through a pull request.