IDEALIT Passport
Menu

Passport search

Find a lesson or fix

Type at least two characters.

    Browse help by symptomBrowse all references
    How to start
    Public course previewThis is not your assigned passport. No identity, answers, or completion progress are stored here.How to start your passport
    Handbook / reference

    reference

    Obsidian (Optional Handbook View)

    View this page on GitHubHow to start your Passport

    Obsidian is a notes application that displays linked Markdown text files. It calls the folder containing those files a vault. Here it is only an optional way to read the handbook after the required setup works.

    Goal: open one clean handbook clone as an Obsidian vault without changing Passport progress or committing local Obsidian state.

    Prerequisites: both Passport Git missions pass and your GitHub account can read IDEALLab/onboarding-IT.

    New to text commands? Read how to open a terminal and run one command before using a command block. It explains the labels used below and what to copy.

    Execution context: Obsidian and Git run on your own computer. Do not run these commands on Euler or Blade.

    Obsidian is an optional way to read the handbook after Git is working. It is not required for the Passport, Git work, Python, Euler, NAS, or Blade.

    The browser handbook is the simplest reading route. Use the clone/vault procedure below only if you deliberately want an offline notes view. It grants no project access and requires no deployment-organization membership.

    Before You Start#

    Complete both Passport Git missions first:

    1. Configure Git Identity And GitHub Access
    2. Complete A Manual Pull Request Loop

    You should already be able to run gh auth status and git status. If either command fails, return to the Git mission instead of troubleshooting Obsidian.

    1. Check GitHub Access#

    Where: your computer, in PowerShell on Windows or a terminal on macOS/Linux.

    gh auth status --active --hostname github.com
gh repo view IDEALLab/onboarding-IT --json nameWithOwner --jq .nameWithOwner

    Expected: the second command prints IDEALLab/onboarding-IT.

    The handbook is public; no lab organization invitation is needed to read it. If the check fails, verify the repository name, network connection, and GitHub CLI login. Ask for help if it still fails. Do not put a token in a clone URL.

    2. Clone One Handbook Copy#

    Choose a normal local parent folder that is not inside OneDrive, iCloud, Dropbox, an existing Git repository, or another Obsidian vault. Then run:

    gh repo clone IDEALLab/onboarding-IT onboarding-IT-handbook
cd onboarding-IT-handbook
git status --short --branch

    IDEALLab/onboarding-IT is the GitHub repository. onboarding-IT-handbook is only the name of the new folder on this computer.

    Expected: the final command reports a branch and no local changes.

    If onboarding-IT-handbook already exists, the clone command stops. Do not delete or overwrite it. Enter that folder, run git status --short --branch, and keep it only if Git identifies it as the expected repository.

    3. Install And Open Obsidian#

    1. Install Obsidian from https://obsidian.md/download.
    2. Open Obsidian.
    3. Select Open folder as vault.
    4. Select the onboarding-IT-handbook folder itself.
    5. Open README.md.

    The vault root is the folder that directly contains README.md, .gitignore, and onboarding_IT_guides. Do not select its parent folder or only onboarding_IT_guides.

    Expected: README.md renders and its local links open other handbook pages. Continue your assigned Passport in the browser; Obsidian is not a second progress tracker.

    4. Keep Obsidian State Local#

    The older mastery path referred to an Obsidian Git plugin. The current setup does not require that plugin. Keep Obsidian state local and update the handbook with the explicit Git commands below.

    Obsidian creates a .obsidian folder for local settings. This repository ignores it. Verify the rule:

    git check-ignore -v --no-index .obsidian/workspace.json
git status --short

    Expected: the first command names a .gitignore rule and the second does not list .obsidian.

    Do not force-add .obsidian, workspace layouts, caches, or personal notes. Do not put confidential project notes in this handbook clone.

    5. Update The Handbook#

    From the onboarding-IT-handbook folder:

    git status --short
git pull --ff-only

    Run the pull only when the first command prints nothing. If it lists changes, inspect them before updating. Do not use a hard reset to discard work.

    Verification#

    • gh repo view names IDEALLab/onboarding-IT.
    • The opened vault root contains README.md.
    • git status --short does not list .obsidian.
    • The Passport still resumes with gh passport open, independently of Obsidian.

    If Blocked#

    • Wrong or empty vault: reopen the folder that directly contains README.md.
    • Clone denied: resolve the GitHub invitation or repository access first.
    • Folder already exists: inspect it; do not clone on top of it.
    • Obsidian files appear in Git: stop before committing and verify the ignore rule. Unstage the files without deleting your local settings.
    • Pull refuses: inspect the local diff and request help; do not force-pull or hard-reset.

    Ask For Help When#

    GitHub access is missing, Git identifies a different repository, the correct vault root remains unclear, or updating would overwrite unexplained local changes. Share only the repository name and the Git error text after removing private notes, credentials, personal information, and private paths.

    Verified: 2026-09-05. Review by: 2027-03-05. Owner: lab software maintainer.