Glossary¶
Short, beginner-friendly definitions of terms used throughout this curriculum, grouped roughly by the part that introduces them. Not meant to be exhaustive — for more detail see the Git documentation or the Atlassian Git tutorials.
Command-line terms (Prerequisites)¶
- Terminal / shell
A text-based program for giving your computer instructions by typing commands rather than clicking. See Prerequisites for how to open one.
cdShort for “change directory”: the command that moves your terminal’s current directory to a different folder. See Prerequisites for a worked example.
- Virtual environment (venv)
An isolated copy of Python plus whatever packages are installed into it, kept separate from your system Python and other projects, so installing something for one project can’t silently break another. See Prerequisites for how to create and activate one.
pipPython’s package installer — the tool behind commands like
pip install some-package, which downloads a package (and its dependencies) and makes it importable from your current Python environment.PATH/PYTHONPATHPATHis the list of folders your terminal searches through to find the program behind a command you type (e.g.python,pip).PYTHONPATHis the equivalent list Python itself searches when youimportsomething. Installing a package properly (rather than running a loose.pyfile) is what lets you skip manually managing either of these — see Part 4: Python Packaging.
Git terms (Part 1)¶
- Repository
A repository (“repo” for short) is the collection of all files belonging to a project together with their complete history of changes. A repository can exist purely on your own computer (a local repository) or on a server (a remote repository, e.g. on GitLab or GitHub), and the whole point of git is to keep local and remote copies of a repository in sync.
- Working tree
The working tree (also called the “working directory”) is simply the folder on your disk where the current, checked-out files of your repository live — the files you actually open, edit and view in PyCharm or your file explorer. It always reflects one specific state of your project (usually the tip of the branch you currently have checked out), plus any uncommitted changes you have made.
- Staging area (index)
The staging area (sometimes called the “index”) is an intermediate step between your working tree and the repository’s history. Before you can turn a change into a commit, you first have to “add” it to the staging area (in PyCharm this often happens automatically when you answer “Add” to the “should Git track this new file?” prompt). This lets you carefully choose exactly which changes should be bundled together into your next commit, rather than always having to commit everything you changed at once.
- Commit
A commit is a saved snapshot of your project at a particular point in time, together with a message describing what changed and why. Commits are the building blocks of a repository’s history: each commit points back to the commit(s) that came before it, forming a chain that lets git reconstruct the entire history of the project and lets you jump back to any earlier state if needed.
- Branch
A branch is simply a named, movable pointer to a specific commit. The default branch is usually called
main. When you want to work on a new feature without disturbing the stable state of the project, you create a new branch, make your commits there, and only merge them back intomainonce you and your reviewer are happy with the result. Branches are cheap to create and are the main mechanism git offers for isolating work in progress.- Remote
A remote is simply a version of your repository that is hosted somewhere else, usually on a server such as GitLab or GitHub, so that you and your collaborators can all synchronize with it.
- Origin
originis just the conventional default name that git gives to the remote repository you originally cloned from (or explicitly added first). There is nothing magic about the name — it’s a label — but almost everyone keeps calling itoriginby convention, so that’s what you’ll see in commands likegit push origin main.- Upstream
“Upstream” refers to the repository (usually a remote, such as
origin) that your local branch is tracking, i.e. the repository you pull updates from and push your own changes to. You will also encounter the term in the phrase merge request (or pull request), where it describes the target repository/branch that a change should be merged into.- HEAD
HEADis git’s name for “the commit you currently have checked out”, i.e. your current position in the repository’s history. Most of the timeHEADsimply points at the tip of whichever branch you have checked out, so movingHEADand moving the branch pointer happen together as you commit.- Merge
Merging is the process of combining the changes from one branch into another — for example, taking the commits you made on your feature branch and integrating them into
main. Git automatically figures out how to combine the changes and creates a new “merge commit” that has both branches as its parents. If the same lines of a file were changed differently on both branches, git cannot decide on its own which version is correct and asks you to resolve the resulting merge conflict by hand.- Merge request / pull request
A request, opened on the hosting platform (GitLab calls it a “merge request”, GitHub a “pull request”), to merge one branch into another. It’s the unit of code review: it shows the diff, lets reviewers comment, and only actually merges once someone approves it (or you approve your own, when working solo).
- Rebase
A more advanced alternative to merging that rewrites your branch’s commits on top of another branch instead of creating a merge commit. Rebasing can produce a tidier, linear history, but it’s more error-prone for beginners and is out of scope for this workshop —
mergeis all you need for now.
Testing terms (Part 2)¶
- Unit test
A small, automated piece of code that checks whether one specific piece of your own code (“the unit”) behaves correctly, by feeding it some input and asserting on the output. “Automated” is the key word: once written, a unit test can be re-run at any time with zero manual effort, unlike manually clicking through your program to check it still works.
- Assertion
A statement (
assert result == 3in Python) that raises an error if the given condition is false. A test function without at least one assertion isn’t really testing anything — it just runs the code without checking the result.- Continuous integration (CI)
An automated process, triggered every time code is pushed, that builds your project and runs its tests (and often its linter) on a clean server rather than only on your own machine. CI is what turns “it works on my machine” into “it works, verifiably, for everyone.”
- Refactoring
Rearranging or rewriting code to make it clearer, faster, or easier to maintain, without changing its observable behavior. A solid test suite is what makes refactoring safe: if the tests still pass afterwards, you can be reasonably confident you didn’t break anything.
- Test-driven development (TDD)
A style of writing code where you write a failing test for a piece of behavior first, then write the smallest amount of production code needed to make it pass, then refactor, then repeat for the next piece of behavior.
Documentation terms (Part 3)¶
- Docstring
A string literal placed as the first statement inside a Python module, class, or function, describing what it does. Unlike a
#comment, a docstring is retrievable at runtime (viahelp(my_function)) and is what documentation generators like Sphinx read to build your API reference automatically.- reStructuredText (reST)
A lightweight markup language (file extension
.rst) used to write prose that gets converted into formatted output (HTML, PDF, …). It is the default markup language for Sphinx documentation, and is what docstrings above are usually formatted in.- Sphinx
A documentation generator that converts a tree of
.rst(or Markdown, via an extension) files into a browsable, cross-linked website (or PDF, or ePub, …), and can automatically pull documentation out of your code’s docstrings (via itsautodocextension).- Read the Docs (RTD)
A hosting service that automatically builds your Sphinx documentation and publishes it as a website every time you push a change, using a
.readthedocs.yamlconfiguration file in your repository.
Packaging terms (Part 4)¶
- Package
In Python, a folder containing an
__init__.pyfile (possibly empty), which makes it importable as a unit (import my_package) rather than just a loose collection of.pyfiles.pyproject.tomlThe modern, standardized configuration file (replacing the older
setup.py) that describes a Python package’s metadata (name, version, dependencies, …) so that tools likepipknow how to build and install it.- Editable install
Installing a package with
pip install -e .links the installed package back to your working directory instead of copying it, so that changes you make to the source take effect immediately without reinstalling — essential while you’re actively developing a package.- Entry point / console script
A mapping (declared in
pyproject.toml) from a command name (e.g.do-nothing) to a Python function, which is what lets you type a plain shell command instead ofpython -m some.module.- Linter
A tool (
ruffin this curriculum) that analyzes your source code for style violations and likely bugs without running it, based on conventions such as PEP 8.toxA tool that automates creating a clean virtual environment, installing your package into it, and running your test suite — so that “does it actually pass from a fresh install” is a single command instead of a manual multi-step ritual.