zine/issues/1/social_git.md

# Being Social With Git

author: ubergeek

## Intro

One underrated social aspect in the tildeverse is collaborating via code
or document creation. Many people consider that to be "loner work", when
in reality, it can be much, much more!

A great way to socialize while creating content such as source code, or
documents, is via git. Git is generally used for source code control,
but it can be used for any arbitrary non-binary formatted file: To do
lists, calendar events, or just plain text files, such as this one.

## Intro to Git

Git is a command-line tool, available for most operating systems, and
installed on every tilde server (Every one that I know of at least), and
there's a reason for that: It is a very powerful tool, used for managing
configuration files, source code for projects from the web
([Github](http://github.com) is one of the most visited websites on the
internet, as an example), and many other reasons. \~team uses git to
edit their website, even!

Git works by creating a database of sorts that tracks changes made to
all files inside of a "repo", or "repository". A repository is just a
directory of files, with the git database files inside of it. One of the
best features of this system is that anyone who "clones" a repo (More
later) has a complete copy of the entire history of the project! Very
resilient to things likes server outages :)

The command "git", by itself, doesn't do much, aside from spitting out
some help info (Which is useful information). It works in phases: Edit
file, commit change locally, then push change to another place (Usually
a shared location for many people, like
[TildeGit](https://tildegit.org)).

There are many front ends to git. TildeGit uses a package called
"[Gitea](https://gitea.io)". GitHub uses their own.
[GitLab](https://gitlab.com) is another one. There's actually quite a
few.

## Git Collaboration

There's a couple of ways you can collaborate with git. One way, is that
each user has a copy of the git repo locally that they work on. When one
person is done working, they "commit" their changes (This means they
write all their changes to be tracked in their local copy). Before
starting work, they "pull" the other person's changes into their local
copy, and then work.

This works well if there is only one other person working on the project
with you. But, what if there are 3? Or 10? Or 50? It easily gets hard to
keep track of whose copy you've pulled in. In this case, most teams have
a central place they store their repo, everyone pulls from there, and
when done with their local changes, pushes their changes.

Another neat feature are "branches", where you can stage changes to be
merged in later, and not have to worry about stepping on other people's
changes until you're done.

If you want everyone to be able to propose changes, but with you (Or a
team) controlling what gets put in as "the one truth", others can
propose a change in a local copy of their own, which you can review
before merging in their change.

Gitea makes most of this process easier by calling the process a "Pull
request". By performing a pull request (A PR), Gitea forks the repo to a
local copy owned by the user doing the PR (You, presumably), where you
can make you change. This also opens a special ticket called a pull
request ticket.

From the shell, the process looks like this:

    git clone https://tildegit.org/ProjectX/neatX.git
    git checkout -b FeatureY
    vi ./module/Zimm.sh (Editing the file ./module/Zimm.sh)
    touch ./subModule/NewFile

This has your changes made, but if you do this:

    git status

It will say there's nothing to do, but you have untracked changes.
`git status` is very helpful to show you what you need to do, in order
to get your changes done. Let's commit these locally:

    git add ./subModule/NewFile
    git commit -am "FeatureY changes, ready!"

`./module/Zimm.sh` already existed, so you didn't have to do anything,
but commit. `./subModule/NewFile` was new, so we had to add it to the
repo, to be tracked.

So, now these changes are in a branch in your local copy. If you want
someone to review them, you need to give them a specific location, and
way to pull your "remote" in (A remote is a copy of the git repo, that
you don't own). Let's say I'm on \~yourtilde, and your copy is on
\~team(Your \~team login name is FeatureXUser), and I (ubergeek) want to
pull it in to merge (I own the repo):

    git remote add -f FeatureXUser ssh://ubergeek@tilde.team:~FeatureXUser/repos/ProjectX
    git fetch FeatureXUser
    git merge ..FeatureXUser/FeatureY

The above adds your copy as a "remote" for me, fetches all of your
changes and branches, and then merges in your FeatureY branch into my
"master" branch. This means all the changes you made are now "live".

Gitea does a lot of this work for you, in a web-based UI, and does some
more legwork (Creates the ticket, notifies the repo owner or owners of
an proposed change, etc etc)