Although this is almost enough to convince me not to start using git (for prose), I’d still like to better understand the short-comings. Apart from the problem of paragraphs being long lines for git, my impression is also that git diff (and pretty much any diff tool?) struggles with larger insertions. (But I may not have understood how to use it.) What I mean is that once you insert a larger chunk of text, whatever comes after that insertion will show up as modified, even though it wasn’t changed at all.
From what I understand, this is because git diff operates on a line by line basis and doesn’t have a large context window that would enable it to notice that a piece of text isn’t actually new but just moved down. I read that git diff --patience tries to remedy this, but I haven’t tried it and I’m wondering whether it is worth trying in the world of prose.
When I first tried git a few months ago in an attempt to share some R and Python code (for data analysis) with a colleague I used git cli commands and found it rather laborious. Part of it may be me climbing the learning curve while what I really needed to do was analyze data, but I sensed that even if I eventually learned the important commands (and understood the overall logic of git) git would still feel like a burden rather that something making things easier. But if the obsidian plugin does most of the version control in the background, it would actually relieve me from overthinking which notes I should split or not split and to what extent I want to document a note’s history…
I’m using git with Obsidian on 1 vault but NOT using the git plug-in. I am a git novice but I found it much faster and easier to just learn the minimum git command I need and run them from the command line. There are really only a very few you actually need to learn to function quite well.
The Obsidian git plug-in only handles an entire vault and the vault I am using has 2 main sections, the database schema creation code and the support technical documentation. So I put those things into 2 separate folders and set each folder as a git instance pointing to a different repository on GitLab (we don’t use GitHub). Works well and we are also syncing that vault to all team members via Obsidian sync.
use the https clone location from the upstream site
git remote --verbose
shows all the remotes you have
git status
Tell me where I am with my local on-mac repo
git fetch origin
This pulls things down but does not merge them into my system. They are just available. If you only have one remote that is origin the command is just git fetch
git pull origin branchname
do a fetch then merge operation if you only have one origin and you have checked out the branch you want already then you only need to do a git pull
git checkout branchname
git checkout -b hcase/feature-branch
Create and checkout a feature branch based on the branch you are at. We use a person’s name as a directory and then the feature branch as it makes the commit history cleaner. This one is for a feature branch that Henry Case is working on. (yes I have read Neuromancer)
git add <modified_file_names>
Stage changes for commit
git commit -m"a short description of your work"
puts changes into your local system
git push
push your feature branch to GitLab
Create a merge request in Gitlab.
- Make sure the source branch is your feature branch.
- Make sure the destination branch is `develop`
I also found that of the visual tools you can use GitKraken has the most understandable picture of the git tree on your repositories. But I don’t use it to do any repo work just to look at what the state of the repo is.
I agree, it creates an undesirably complex workflow without adding any real advantages. Pages and Time Machine have you covered.
I use GitHub for coding but would not use it for writing, neither group or individual work. It only really shines when built into an IDE like Jetbrains, as they have an awesome AI that writes commits for you and everything is automated (no going back to 1980s style terminal commands required!)
You would more likely spend days tweaking it to make it work for a purpose it’s not designed, and not get any writing done!!
I appreciate you sharing your cheat sheet (I copied it into my notes), but I can’t help but notice that it also proves exactly this point:
I don’t understand half of what‘s in the cheat sheet (which my problem, not that of the cheat sheet). From last time I used git, I remember what remote means, but I slready forgot what origin means and I don’t know what an upstream site is. And the whole thing with branches is giving me headaches that I probably would avoid using them (at the cost of missing perhaps one of git’s strongest features). And so on and so forth…
Upstream are the places you can send you updates to. More important for open source items where you do not have write privleges on the main repository. You basically make a copy under your username and you can then push your changes up to it. When you are ready you do a merge request to the origin, basically asking the maintainers of the open source project to allow your updates to be added. The extra layer is so that it’s harder for nefarious code to creep into an open source repo. Not impossible, but does require more effort. And because you can trace where it came from youc an find and block that user in the future. Also the open nature means more people wil see the problem code and catch it.
Branches are your friends. You can test multiple options. So in writing documentation I have the main published branch of the AnimalTrakker® manual as main. I decide I’m going tototally rearrnge it and so I make a branch. In our system I put my branches and changes into a subdirectory with my name so everyone workingon the project can see who did it but if I was the only person I’d just create a branch
My new branch is called oogiem/docs_reorg
I can work with all the files there until I am satisfied it works and looks ok. To save my work I push early and often to my upstream remote. When it’s all ready I can then ask the maintainers to merge it in to main.
In a novel I can use Git to play with scenes, decide I don’t like that whole thread of action and end up moving it to a subsequent novel or a short story or just prphaning that branch and trying something else
Branches are like scraptch paper you can use to test thigns out before committing to using them.
One more I’ve seen (which you’re probably already aware of) for those writing long texts in Markdown stored in git is to split paragraphs up into short phrases, with a single phrase on a line.
That’s apparently because Git (by default?) only compares versions on lines, not on individual words. If you write paragraphs ‘normally’ (using soft-wrapping, and marking paragraphs with double returns), then Git will mark the whole paragraph changed if only one word has been altered – not always convenient with long paragraphs.
But as Markdown ignores single returns, you can use this to split the paragraph into shorter lines, which makes identifying the precise location of changes easier.
In other words
if you break your paragraph down into phrases,
one per line,
the job of using diff tools
to find the mistakes you've corrected
or other changes between versions
is made easier.
In other words if you break your paragraph down into phrases, one per line, the job of using diff tools to find the mitsakes mistakes you’ve corrected or other changes between versions is made easier.
You still use double returns to mark the end of the paragraph and Markdown and HTML still render the paragraph properly.
Derek Sivers recommends this a good technique even if you’re not using Git… [Writing one sentence per line | Derek Sivers] Writing one sentence per line | Derek Sivers but I don’t think the idea originates with him.
I’m converting my site right now to Astro. It’s such a great framework once you get the hang of it. The community is unbelievable, and hopefully more people move over to Astro. Hopefully more bloggers will use it and teach businesses like squarespace and wix a lesson about portability.
(which my problem, not that of the cheat sheet). From last time I used