Use Git in the browser if you can
17 Dec 2024
Opinionated hot take: don’t bother downloading copies of Git repositories onto your desktop computer. Just edit them in your web browser.
If you don’t ever need to personally execute the code you store in GitHub.com, Azure Repos (part of the Azure DevOps suite), or GitLab, you don’t need to waste your time learning a bunch of complicated, nuanced Git features.
Just hit period for a fancy web editor
Instead, when you’re looking at a non-empty repository in your web browser, just hit the period key on your keyboard (.) to pull up the repository in a lovely little browser-based version of the Visual Studio Code (“VSCode”) integrated development environment (“IDE”).
Good enough for Salesforce is good enough for me
Synchronizing a Git repository between its cloud host and your desktop computer isn’t nearly as “automagic” as you might be used to with something like Dropbox or OneDrive. (It’s a complicated on purpose, because Git was invented by programmers, and programmers love to trade a little convenience for a lot of fine-grained control.)
Luckily, it’s a royal pain that you might not need to deal with at all, because web-browser-based editors have gotten incredibly good in the 2020’s.
No more “remote” and “cloning” jargon required – just edit things right where they live!
After all, if you’re a technical writer, you don’t write code that you need to execute on your desktop computer to know whether or not you did a good job.
You write paragraphs of plain English. You’ll know if you did a good job just by having a snack break and looking at it with fresh eyes.
Analogy: the desktop version of Microsoft Outlook doesn’t send your email to your colleague any faster across the internet than outlook.office.com does. There’s nothing technologically special about desktop vs. web browser when it comes to getting plain English where it needs to go.
So why worry about the complex mechanics of synchronizing a copy between the cloud and your computer?
When I helped edit documentation during a Salesforce Open Source Commons community sprint, we exclusively used GitHub.dev. No participant ever installed a thing onto their own desktop computers.
Modern web editors work really well for tasks like editing documentation contained in README.md files.
Bonus: you can use web editors from a smartphone when you need to fix a typo on the go!
Don’t let anyone tell you the web editors aren’t good enough.
They probably just haven’t given the advanced web editors a fair try recently.
Note: I’m not talking about the older basic web editors that clutter up your project’s history by forcing you to do a Git “commit” for every single file you edit.
Those still exist, but you can pretty much ignore them now.
Old-timers often fear newcomers will accidentally fail to follow the team’s agreed-upon style etiquette for “commits” and “branching” if they don’t use a serious enough editing tool.
That’s a fair and valid concern!
Luckily, the newer advanced web editors can do everything that the desktop-based editors can do in this respect.
I use them all the time, and I think you should try them, too.
Prereqs
Log in
You must, of course, be logged into GitHub / Azure Repos / GitLab through an appropriate username.
Non-empty repository
Tip: If the repository is currently empty (that is, it has no file-commit history), use the service’s old-fashioned browser-based basic file editor to add 1 file, such as a blank file named README.md or .gitkeep, to the home directory or something.
Ta-da – now the commit history has an entry in it, and . will work from here on out.
Here is some basic-editor documentation for various platforms that provide Git repository hosting:
- GitHub Repositories - managing files lets you create any file you want, even in an empty repository.
- Azure Repos’s web browser interface doesn’t seem to offer anything for empty repositories that gives you quite as granular of control over filenames or their contents as GitHub does. However, an empty repository will always have an Initialize button at the bottom that can be used to add a
README.mdfile, a.gitignorefile, or both. Delete or edit it later if you don’t like Azure Repos’s default file contents. - GitLab - web editor possibly works on empty repositories?
- GCP Cloud Source Repositories doesn’t seem to have a browser button for creating a file in an empty repository, so partner with a colleague who understands doing Git from their desktop computer to add a file to the repository to get started. (They can even also delete it for you! There just needs to be some file-modification “commit” history for the repository to be considered not-empty.)
- AWS CodeCommit - working with files seems to be able to create files in empty repositories.
- OCI Code Repositories - manage files seems to be able to create files in empty repositories.
Generic web IDEs
The best things about the VSCode-based advanced web editors (which most of them are) is that the tooling available through the Source Control badge in the Activity Bar over at the far left, in its More Actions menu (three dots to the right of the “SOURCE CONTROL” heading), have been modified for user-friendliness, as compared to the desktop version of VSCode:
- Added in web version only: Pull Request
- Simplified sub-options: Branch
- Removed altogether because they only apply to working with Git on a personal computer: Clone, Checkout, Remote, Stash
- Removed altogether because there are more user-friendly ways to deal with them elsewhere in the web browser: Tags
Getting started: GitHub.com’s documentation for navigating the GitHub.dev advanced web-based editor is excellent and should be more or less transferable to all of the VSCode-based advanced web editors listed below.
This is the typical “day in the life” workflow you’ll be following whenever you edit the contents of a Git repository, no matter which web editor you use:
- “Branch” off a new copy of the files as you sit down with a fresh cup of coffee and crack your knuckles.
- Create/Edit/Delete files and folders at your leisure.
- Tip: Just a few hours’ worth of work, though, please. Only bite off what you can chew quickly before proceeding to step 3.
- Merge your work back into the long-lived shared copy of the files with a “pull request,” deleting the branch you created earlier like throwing away scratch paper. Do some chair yoga and refill your coffee.
- Need to make some more changes? Repeat from step 1.
GitHub
“.” opens GitHub.dev.
Alternatively, if the URL of your repository’s file browser is https://github.com/YOUR_REPOS_OWNER/YOUR_REPO, then opening https://github.dev/YOUR_REPOS_OWNER/YOUR_REPO instead will open GitHub.dev.
(Technically, you can also open a GitHub repository in VSCode.dev, but it’s not the default behavior of the period key and I’m not sure why you’d care to. If the URL of your repository’s file browser is https://github.com/YOUR_REPOS_OWNER/YOUR_REPO, then opening https://vscode.dev/github/YOUR_REPOS_OWNER/YOUR_REPO instead will open VSCode.dev.)
Azure Repos
“.” opens VSCode.dev, which works just like GitHub.dev but tends to start in dark mode, whereas GitHub.dev is more likely to start in light mode.
Alternatively, if the URL of your repository’s file browser is https://dev.azure.com/YOUR_ORG/YOUR_PROJECT/_git/YOUR_REPO, then opening https://vscode.dev/azurerepos/YOUR_ORG/YOUR_PROJECT/YOUR_REPO instead will open VSCode.dev.
GitLab
“.” opens GitLab WebIDE, which seems to be the same idea for GitLab.
It also looks VSCode-based, glancing at its docs’ screenshot.
GCP
Google Cloud Platform’s (“GCP”) Cloud Shell Editor seems to be the same idea for GCP Cloud Source Repositories.
It looks VSCode-based, glancing at its docs’ screenshot.
Amazon Web Services
Amazon Web Services’s (“AWS”) Cloud9 looks like a similar idea for Git repositories hosted on AWS CodeCommit.
However, glancing at it screenshot, it might not be VSCode-based.
Specialized web editors
All kinds of cloud-hosted infrastructure/platform services can often auto-sync to various Git repositories.
Azure Data Factory
ETL tool Azure Data Factory, when provisioned in Azure’s Commercial Cloud, can auto-sync the configuration you do in its point-and-click web editor (“ADF Studio”) to a Git repository hosted at GitHub or at Azure Repos.
Power Platform
Low-code application development platform Microsoft Power Apps can auto-sync the configuration you do in its point-and-click web editor to a Git repository hosted at Azure Repos.
OCI Visual Builder Studio
OCI Visual Builder Studio seems to be able to edit the contents of Git repositories hosted on OCI Code Repositories, but seems to be for editing only repositories containing certain types of codebase, not an all-purpose editor.
