Re: literate programming, development log -- ideas? (ominbus reply)

[Tim Cross <theophilusx@gmail.com>]

"Samuel Banya" <sbanya@fastmail.com> writes:

> Hey Tim,
>
> Wow that's an awesome idea too aka to create local branches on each machine, and then switch over the master branch to pull them in.
>
> Do you have any video references for this kind of thing?
>
> I like videos first, and then documentation.
>
> It would really help me out since I'd love to try to figure this kind of thing out, since I am pretty close to just using rsync for my Git notes going forward,
> but needed that kind of convincing otherwise.
>

Sorry, no video links/references. There are lots out there, I just don't
watch them. I think one of the best ways to understand git is to just
use it at the command line and experiment. Git can appear daunting, but
it is actually fairly easy. It has a huge number of commands and
options, but 90% of the time, you really only need a very small handful.

The nice thing about learning a VCS is that you can clone a repository,
experiment as much as you like and when you make a mistake, try to use
git to undo it, but if all else fails, blow away your copy and clone and
try again.

Probably the biggest complaint I see about git (or almost any VCS) is
merge hell. However, this can be largely avoided with a few simple rules
and some discipline in your workflow. People often get into this type of
mess because they make lots of changes before committing them and
because they make changes on the master branch rather than a topic
branch.

I almost never make changes directly to the master branch. I will create
a new branch for even small changes and then merge it back into master
once the changes are complete. Sometimes, I forget and realise I've made
changes which should have been done in a branch. When this happens, I
use the 'stash' command to stash my changes, create a topic branch and
then apply the stash to that branch.

If a topic branch has existed for a while and you know the master branch
has diverged significantly since you made your topic branch, it can be
useful to rebase your topic branch against the current master branch.
This will effectively apply all the changes from master to your topic
branch *before* then applying your changes. It is like you have just
forked your topic branch from master. You may still get some conflicts
when re-applying your branch changes, but there will typically be less
and they will be easier to resolve. 

If your working on a project with lots of contributors, where master
changes quite quickly, you may want to do frequent pulls and either
merge or rebase into your topic branch. Merge conflict really only
becomes a pain when there are lots of changes to all apply at once. If
I'm working on a large project with lots of contributors, I might do a
pull and merge or rebase into my topic branch every day (maybe multiple
times per day). On a private repository, I will do this far less often
because I know what has changed and when it is a good idea to merge or
rebase my current topic branch.

Provided some discipline is applied, I find when it comes time to merge
my topic branch back into master, it is a straight forward merge with no
conflicts and changes in master remain clean. 

It is sometimes a good idea to poke around a bit in the .git directory
and get to understand what is in there and how it works. It is
surprisingly simple once you understand the structure. One of the things
I like about git is that it makes simple things simple and hard things
possible.

Sometimes, using some sort of sync software is the right solution. I
regularly use rsync for a number of tasks. However, I use git and remote
git services like gitlab or github for all of my projects and org notes.
Some people prefer Mercurial (hg) over git. I think it is a fine VCS as
well and often use it too. It has many of the same concepts and can be
used in a similar manner. For some people, it sits better with the way
they work/think than git. However, the core concepts are the same.