View source for Git notes

{{#addbodyclass:tag_tech}}
{{#addbodyclass:tag_prog}}
{{Content versioning}}
{{stub}}

__TOC__



==Waffling about mental models, and "For those coming from other versioning systems..."==

{{stub}}

<!--

'''Sooo git's a bit complex'''

Your introduction to git is probably going to define your levels of pain for the next year.

The earlier you understand its model ''well'' the better off you'll be. 

...but no one explains it very well, so most of us learn just enough to function.
Because that's what is most important of a tool - it needs to function.

Besides, you won't even know what you need to know, what questions to ask, 
so are you going to learn ''all'' of it immediately? Of course not.

And there are many more terms than any other versioning system. Files, a working tree, an index, a local repository, a remote repository, remotes, commits, branches, the stash, the index, tree-ishes, refs, the reflog, tags, remote branches, tracking, namespaces, fast-forward commits, squashing, detached head state...  You confused yet? There are more.

To say git has a problem with [[leaky abstractions]] would be wrong - it has no abstractions at all.


Say, something like [[subversion]] has only a handful such concepts.
You have a repo, your working copy; everything's a file, files have revisions decided by the repo, there are tags, there are branches (which are mostly just tags). 

That's most of what you need to know. The mental model is half as complex.

That's not to say subversion is better, it's more that when simpler models is enough, you're done learning/reading a lot faster.  Which feels friendlier to me.



'''"So when is git the best tool for the job?"'''

Do you do work independent from others? 
Heavy on the branches?
Do code review?
Have some teams you communicate with more often than never, but a lot less than everyone else?

Do you care to take unsolicited contributions?
Not that is is a bare-git feature per se, but it seems using bare git means you're a weirdo? 
We use github, gitlab, bitbucket, and a slew of clients that do their own thing, IDE integration things, and maybe some extra manager on top (e.g. gitkraken).

Do you want others to suggest merges into your code?


None of these point ''exclusively'' to git (the last one sort of),
but git can be more capable toolkit (toolshed?) to work in. 

But, at the same time, can be too complex when your needs are very simple.



'''What are the differences, ''really''? Why choose git over others?'''

That's something only you can answer. 
: ...for both of those questions, actually, because if you don't use all the features, there may be no effective difference.


For all of my hobby code, I only care about history - and I do ''not'' choose git for this, purely because most alternatives are fewer keystrokes (and fewer rough edges around conflicts - but those are rare because they would be with myself).

I use git mainly because I forced my own hand by putting stuff on github/gitlab.

You would use git when you needs its fine grainedness. 

Or the project you work on made the choice for you. 

Or you just have some tooling you like.






The need for git came from linux kernel development, which is an unusually large community that is organized in an unusual way.  They needed something more flexible, more participatory, more democratic than most, with more care about code lineage.

Most open source of company teams, though? Not described by that. At all. 

-->

===Asking what and why===

From a distance:
: Git is a content/source versioning system. 
: One of many. 
: A bit more flexible than others - and a bit more messy than others as a result
: Currently popular.



====What do you even use it for?====

<!--
If you have a bunch of programmers on the same team, 
you need ''some'' sort of code versioning to keep sane while you make (hopefully distinct) changes in the same set of files.

Whether you're in a team or alone, it is also a nice way to keep a history of past changes. 
It's not ''quite'' the same as backup, but it's similar safety net.

For the most part, any source management system covers these bases,
and work very similar to each other.


In the real world you may also have the concept of people sending in unsolicited code.

''Bare git'' is arguably no better than the classical 
"here's an email with a diff to some recent version, good luck",
but ''git as used via github/gitlab'' is sort of nice for this,
primarily because that forces other people to do more prep work,
and will send it to you in a specific way that you can deal with more easily.

-->



<!--
The most basic form of code versioning, particularly when you are alone:
 [[File:Most basic versioning.png]]


If we now change four things at once: 
* working in a team
* using git
* and specifically using git on github/gitlab
* not all having equal access to the repo
Then the mental model is more like:
 [[File:Git basics.png]]



'''Isn't that an unfair apples and oranges comparison?'''

Absolutely!

The first is mostly a "save all changes since yesterday" use,
the second has a lot more potential uses and flexibility.

In particular,
github/gitlab allows contributions to other people's code projects, and code review,
while the first just requires you to be a team that you give full access.


Still not pictured in the second, though: 
* git's stash, which is sort of a whole separate "separate index of postponed things"
:: left out because not everyone likes to use it
:: ...for everyday use, anyway; you regularly sort of need it for conflict resolution
* conflict resolution 
:: in theory, git's resolution is no more complex than in other code revisioning
:: in practice, ''yes it is''
* branches 
:: a topic in itself
:: similar to every other system with branches
:: plus some extras that seem to be worth a little more complexity



'''One of the good answers to "why?" is separation of commits''' 

Git really suggests you think not in "all changes since yesterday" but in individual, isolated, functional changes. 
This in part because once you need to do conflict resolution, 
it is ''really'' handy when specific commits represent functional changes you can make decisions on.

That's ''always'' a good idea, arguably not at all specific to 
git, but whenever git makes you juggle changes, you ''will'' thank yourself and others for following this advice.



When you're a handful of people working on the same code, you can probably still feasibly say
"hey, can you not touch the rendering code for a few days? I'm refactoring it" and a few days layer commit a bulky 
"this is new cleaner rendering code".

In a team of hundreds, you would still speak those words, but you would not expect that commit to be 
: a) without conflicts and 
: b) accepted as-is


Git really suggests you think instead in individual, isolated changes in packets that are meaningful to work with - meaningful to the origin repo.

This is the approach you likely want in larger scales of project. 


Chances are you don't make changes in purely isolated sequences, so (UI and time permitting - the CLI is... not great for this) 
you separate your changes into commits that can be understood as "the various file changes that change X". 
Also so that reverts, and code reviews, work on more sensible units.

Can this be overstated? Yes.

Does it take time that could instead be used producing code? Yes. 

Can it take unreasonable time? Sometimes.

Is it often useful? Also yes.  

Does it make working in larger teams less messy? Often yes.



----


All this is even more true when the repo is not yours to begin with.

Contributions are ''very much'' expected to be clean, reviewable packges.

(see also pull requests)






-->



<!--

Git has more goals


It was designed with code review in mind.

Sort of. Not like how we use it, actually.

Code review was classically seen as a separate thing from code versioning - and still largely is, because there are multiple styles of doing so. You can do it separately, afterwards, in branches, and all of those are options in all source versioning.


Git doesn't work fundamentally differently
It sort of does, but the way we ''use'' it, e.g. pull requests as implemented on github,
are ''not'' a core git feature. 
It's just something that various git-hosting sides have added, on the web side.





Arguably, '''before you should ask ''how'' is it different, you should ask ''why'' is it different?'''


And sure, it's more flexible. But it is also much harder to learn, so there ''must'' be a very good reason we are spending more time on weird git edge cases that keep us from writing actual code, ''right''?

Its design seems influenced more by the peculiarities of a single project (the origins of git are the linux kernel project),
where code review at a large scale needed to be possible.


Which is something most of don't need so much. 
Code review is possible in other systems, but a ''little'' more flexible in git.


-->
<!--
It is more flexible than various others.

[https://stevebennett.me/2012/02/24/10-things-i-hate-about-git/ To paraphrase],  
: It's a pity, then, that it is so so bad at explaining how it works,
: has a CLI so messy that it doesn't fit its model very well,
: and makes learning even harder,
: and (by extent) that it doesn't care about its users.


There is a reason the CLI is confusing -- it grew organically[https://www.youtube.com/watch?v=qs_xS1Y6nGc&t=769s]
so new operations things got attached to the closest existing command under a specific parameter. 
Some of those get picked apart after a time
(that bit was [https://www.infoq.com/news/2019/08/git-2-23-switch-restore/ quoted when switch was introduced]),
others remain major gripes because it means that understanding git's CLI 
is acknowledge to be a poor way to understand git itself, with a few things approaching demi[[god objects]].



So it's ''not really'' about letting people work independently.

A largeer inflence

It seems that onAggregation of code review 

The break is arguably most related to its origins (the ), where 


That said, almost no one uses it that way, because within stable, organized teams
this is neither necessary or particularly useful. 
The added complexity of having no centralization just has more cost than benefit.


Particularly before you understand git on a deeper level,
and most people only know enough to get themselves in trouble.

-->

====Why git and not something else? How to choose?====


<!--
The basics of add, commit, push, pull is basic enough in any sysytem.

Basic branching and basic conflict resolution is also pretty similar.


The stuff you can ignore is also there in every system. 

Git has ''more'' of it, but since you're ignoring it, that's fine.


A valid argument to maybe go for something else is that almost everything else is easier to learn.

A valid argument to go for git is that it's easier to communicate with other people using git.


It's that git's more complex model means conflict resolution is messier. 
It's hairy enough in the most polished cases, but 
git's just has a lot more edge cases that you will waste half an hour googling'' than anything else.





This because git in its most flexible form is also more complex, with more edge cases. 
For smaller projects, you may still consider simpler systems with fewer edge cases. 
You'll spend less time googling how to resolve very specific conflicts, and more time coding.



So compare to subversion (centralized), mercurial (distributed), bazaar (distributed), and such.
-->
<!--

For example, for small, tight-knit teams with clear responsibilities, or individuals just wanting code history, you probably work centralized, and git may have no added value over simpler code versioning.

And the largest difference is more edge cases to trip over, and complicated resolution, and more people spending their first days using it doing as much googling as coding.


: subversion
: mercurial: distributed
: bazaar: distributed, simpler to deal with than git[http://wiki.bazaar.canonical.com/BzrVsGit#Bazaar_vs_Git]
-->

<!--
Also note that in practice, if you use a GUI frontend or IDE plugin, the choice of that plugin actually matter more than what backs it.  Particularly the way it deals with conflicts.
{{comment|(I've seen people much more learned in git just wipe their copy ''because that's faster than figuring out the specific way git and/or their frontend was confused because they know it's a buggy plugin)}}

And sometimes integration into workflows is important for product management reasons.
-->

====Comparing purposes====
{{stub}}


<!--
In theory, git is potentially wildly different from classical 

In practice, it's almost the same
-->


Perhaps the largest mental switch is that 
* in respository style, you can intuit a commit as "the new revision that everyone should have" 
: and global to all users of that repository

* in git's style, a commit basically just identifies an annotated collection of diffs
: which in itself, is local to a copy, not something reflected elsewhere until you make that happen





"in git, everything is local" is meant to say that every copy is an independent, complete, standalone thing.


That's a real difference, but not really the point. 
It's a side effect of the distributed graph nature.


It also helps to mention 
''why'' was designed this way,
''how'' it is different from other setups,
and ''when'' you might want one over another.



'''Git is distributed in nature''', more specifically a distributed graph, '''but almost no one uses it quite that way'''

The main alternative is is diverging from is the ''central repository'', where
: the only place everyone communicates with is that central repository
: the only place where things get committed is that central repository. 
: working copies can never diverge much from that repository - the more and longer they do, the harder it is to ever exchange with again
: the concept of "a chunk of changes" is basically "whatever the difference between this version and what it was in the last version"
: the repository is the only thing that tells you how to refer to each revision (which may be a version counter)
: and that's really the only kind of "make changes in the system" operation there is


Git has a different take on all of that:
: that commit is local to your copy - but can be communicated
: every copy can communicate with every other copy (though in most use you still use a central place)
: there is more focus on what ''content'', rather than version {{comment|(...though there is no hard distinction in the end)}}, any commit is relative to 
: as there is no central authority, revisions can't be referred to by version counter


...no one uses it that way.

Most people host on github or gitlab or similar (it seems people shout at you if you don't) - which are repository style setups.
The mechanics of exhcange and references are different,
but the basic model of exchange mostly isn't,
and it is no less likely than others to throw a fit when changes conflict.



'''But why?'''

The means of resolving conflicts does not actually vary a lot with the underlying data model,
because the problem is generally the same.

And clear communication is typically worth more than the technical part of the solution.




'''If you communicate often''', then a central repository is a fine solution,
and the setup ''forces'' you to communicate.
: Even the kernel project has some strong guidelines - and a central repo on github.



'''Ad hoc use''' is possible, but just ''not done'', because it's more trouble than it's ever worth.



If '''people typically work independently''', with less or later communication, but still mostly on the same thing,
then you need a much better defined idea of "this is the set of changes I want to communicate"

The fact that git thinks more in diffs (and less in "you are working on whatever will be the new version, which we ''can'' also see as differences" to whatever the previous central version was) turns out to be more practical for such use.



This also leads to the git's staging -- if you're working on whatever becomes the next revision, 
then you need not make life more complex than committing that new version to the repo. 
It'll tell you if and when you need to do some conflict resolution.

But if you need to commit what is essentially a diff, you need to figure out which specific differences you want to transfer. 
Git makes a point of ''locally'' giving a name to a change-set.
(This is also roughly why commits are always towards your own copy.)


To be fair, when that's "all changes you've done", there is very little difference.



But the ability to split diffs into more commits also makes [[code review]] easier.

This is an important detail for the linux kernel project, because it runs on a benevolent dictator model.

===A little more on the waffling side===

====Relevant snark====


* "If the power of git is sophisticated branching and merging, then its weakness is the complexity of simple tasks."[https://stevebennett.me/2012/02/24/10-things-i-hate-about-git/]


* 90% of people don't need 70% of git
:: and may specifically want to avoid it, because why invite extra edge cases? Who wants to learn them if they will never use them?

* ...also, that ''other'' 30% is more complex than it is in other systems.
:: At this point the training wheels are off. There are no abstractions, and there sure are a lot of technicalities.

* the CLI should ''absolutely not'' be how you learn git's backing model. 
:: because the CLI is already a layer of pragmatism on top of it, so will be misleading
:: For example, ''{{inlinecode|git reset}} can do half a dozen different things'', in terms of the underlying model.
:: there is a reason that the CLI is sort of a bad way to learn git - it grew organically and new operations got tacked onto the closest matching command


* git can be smarter at handling conflicts than some alternatives
:: '''but''' when it hits something it doesn't deal with, you better understand git at a ''deeper'' level than the same alternatives. Good luck! (hint: most of us are just pretending, or haven't found such a case yet, or did the "wipe copy, start over" thing)

* more power and flexibility means more edge cases, that you will have to learn sooner or later
:: ...usually in crunch time when git throws ''yet another'' error you've never seen before

* sometimes the best way to resolve errors is to wipe the project and upload a new copy
:: unless you're one of the people who actually uses it distributed, in which case - Good luck!


* there is a reason github/gitlab specifically imitates classical repositories
:: and considers a linear, squashed history to be 'protection'[https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches]

* Git becomes easier to ''use'' once you use third party wrappers instead
:: ...some of them add convenience that become hard to live without (beyond IDE integration)
:: ...though each one will have their own workflow, none of which are quite the same

* github/gitlab has a bunch of of actually-quite-nice tooling
:: ...to deal with things that happen only when you decide to have zero communication with [[upstream]] before a lot of code is changed (...that the upstream maintainers will typically reject the first version of anyway)
:: also, this tooling isn't really part of core git

* people seem to not tell be able to tell git apart from github/gitlab
:: so we're fine with microsoft feature-controlling even more of our go-to open-source dev environment, then?


* why does that two-line merge take a minute? 
:: Who can tell? 
:: Probably your fault though.
:: (cue long discussion about packfiles, how purges would fix this but are a bad idea, etc.)


* don't use git as backup, because there are several ways you can wipe out contents ''permanently''
:: so have your own backup 
:: incidentally, backing up git is hard to make correct and fast at the same time (especially if you like repack)


* git is a classic case of "when these dozen previously things vague snap into place, you will suddenly get a lot of it". 
:: Until that point you will be actively confused by the fact that you will ''not'' be tutorialized, and some concepts are explained poorly and even a bit conflated.
:: ...seemingly conflated for the sake of those who already get it to make more concise sentences, at the cost of all learners. (I personally think that was a bit of a mistake, but hey.)

* "Git becomes a lot easier once you understand that [x]" 
:: ...almost invariably means "I stared at it long enough to internalize enough of it to sort of get it"
:: and almost never means "I now produce a statement that will help you understand it more easily", maybe unless you were almost there already (And even if it does, you won't know it from the ones that don't)

* git's documentation seems so adverse to actual explanation that it is nigh impossible to understand unless you ''already'' understand git well
:: every page one uses terms that it doesn't explain. By the time you've found definitions you've read most of everything and wasted at least one workday.
:: Say, git-rebase says it "forward-ports local commits to the updated upstream head". 
::: Uhhuh, uhhuh. 
::: That ''sure didn't say that'' 
:::: ''content-wise'', it's taking changes on one branch/copy and figuring out what sort of commits you need to do to make the same changes on another branch/copy, and put that in a new commit, 
:::: most people's ''intent'' is to send a simpler commit to another clone/copy (in a pull/merge request), or even towards yourself to isolate iterative commits to branches to then ''collapse'' once you're done with each, or that you're specifically doing non-linear things to the end of keeping the ''main'' branch stay quite clean and linear
:::: and that more technically, the point is that your commits are against an earlier version/commit, and rebase allows you to ask "git, please take this ''later'' version/commit and figure out the diff/commits against ''that''
::: All that may be obvious once you know that, but, um... what is documentation for again?
:: [https://git-man-page-generator.lokaltog.net This is about as legible]


<!--
https://git-man-page-generator.lokaltog.net/#aWdub3JlJCRiYWNrdXA=

https://www.atlassian.com/blog/software-teams/mercurial-vs-git-why-mercurial
-->

====Team contributions versus unsollicited contributions====


While we ''can'' playplay [[degrees of separation]] in terms of code -- e.g. A contributes to B, who contributes to C, as does D -- we tend to not do that because when E comes in, they don't know ''what'' is going on.


Most projects, at small-team or company scale, have a vested interest in communicating well, tightly, and understandably.

So we usually avoid the anarchist web structure because when you communicate well ''anyway'' it's more trouble than it's worth, 
and if you ''don't'' communicate well it won't save you (and it may make things worse).

So we typically still organize with what ''amounts'' to a central repo. 
And most of us use gitlab/github, which is definitely central-repo style.


[[File:Code_versioning_real_world_git.png]]


{{zzz|
And yes, you could remove that "somewhat indirectly" part by giving anyone access to your repo, 
and this is still fully possible with git, and github, and gitlab, and more,
and might make sense if you are a small, well defined, fully trusting dev team.

But to get some granularity, particularly in a more decentralized world, we do not trust anyone by default. {{comment|(Github makes you think about restricting even collaborators from doing pull requests, and considers ''that'' protection too[https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches])}}
}}

{{comment|(Actually, github '''suggests''' history sticking to linear history, and collapse into functional changes, meaning you may want to ''require'' contributors to do their own [[squash merge]]s or [[rebase merges]] first.  It, in fact, considers this to be a form of '''protection''' of the central repository[https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches])}} 





'''Unsolicited changes were always their own special case, and still are, and probably fundamentally always will be.'''

Before git, people tended to send you a diff via mail and have the you, the developer, figure it out.
It was out-of-band, and if you had developed on, ''you'' had to figure out how to still make that merge fairly manually.

With git, the habit is still "you get to ''propose'' a change for the dev to look at".

Yet it's not ''quite'' [[in-band]]. That is, pull requests are not part of git. Yes, really. 
So it's still sort of [[out of band]], except that the tooling is now nicer -- yet specific to the hosting
(github, gitlab, etc - it's part of why self-hosting git is not common).

Because github or gitlab have features that help you here. If you don't use those, and aren't Linus, well, it's clunky.

We are describing merge requests, a.k.a. pull requests. In that diagram, this is what that "somewhat indirectly" hints at.

===A ''little'' more practical===

====On confusing terminology====

Arguably, there is a some not-great naming going on.

Heck, git can't always even agree with itself. 
Depending on context, it uses 'index', 'stage', or 'cache' which are the exact same thing.



It may be easier to understand if you consider [http://www.sabi.co.uk/blog/20-two.html?201206#201206 (stealing from here)], [https://jvns.ca/blog/2023/11/01/confusing-git-terminology/ (and a little from here)]:
: "index" could have been called the "draft snapshot" - its intent would be clearer
: "commits" could have been called something like "(possibly-annotated) snapshot of the whole" (maybe, I'll think about that one)
:: though because of the nature of this sort of repository, commit is ''frequently'' thought of as "just the subset that is the difference that that makes"
: "branches" could have been called "snapshot lineages".
: "repository" could have been called the "snapshot store".
: "stash" could have been called the "content drafts".
: "working tree" could have been called the "content pool".






<!--
'''Does git think in full versions, or in diffs?'''

Yes. 

Both. 

This is a distinction most versioning systems keep fuzzy, and it turns out git is no exception.

And that makes sense, because this is a ''pragmatic'' answer:
for some commands it really pays to think of it as one rather than the other.



'''Somewhat more usefully -- but low-level:'''

The core of git is really a key-value store. 

Each revision is a separate object in there. The most basic way to address it is by the hash of its contents (called hash, or oid).
At this low level (that you do ''not'' need to learn), there aren't even inherent relations between these objects.
Things like commits and diffs are ''not'' part of this lowest level yet.

When you do commits, you start relating objects to each other.

Diffs are an ''implication'' of the relations you set up.

The graph (more specifically [[dag]]) that you make is not part of that lowest kv level, 
''but'' at the same time is so permeated to so many commands, and so much of what git does,
(various higher level concepts end up being a reference to a commit id) 
that it might as well be.

While diffs aren't a [[first-class citizen]], 
some ''operations'' are fundamentally very diff-like.
''In particular'' things like [[rebase]] have to be, by nature of what they do. 
{{comment|(also git gc compresses based on diff-style logic, because unsurprisingly that's great way to do compression of very similar files)}}

https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain



'''"What is a commit, really?"'''

A lot of versioning systems are fuzzy on whether a commit is a diff, or a state in time. Git is no different.

'''A commit is snapshot.''', often what you would consider full versions (of a branch{{verify}}).

{{comment|(...but again, we often ''think'' of a commit in the sense of what changes get you to that next snapshot. Technically it is only a snapshot by ''implication''  at low level, it is only one node that is only one difference, but in the graph it implies the rest (all commits, back to a root tree?))}}

Also, it often doesn't refer to everything in the repo -- ''largely'' (but not only) because branches are a thing.


However, an object is stored as-is. 
It is not a diff, it is the thing. 
Object files are the full thing, which is how they can be content-addressed.
Even if a packfile tries to do delta compression stuff, the thing that comes out is the full thing.






'''"Okay, what is a branch?"'''

Two or three different things, that we can ''usually'' safely [[conflate]].

A branch is a subgraph of the dag -- all the commits reachable from a certain branching commit. {{comment|('reachable[https://think-like-a-git.net/sections/graph-theory/reachability.html]' is doing some heavy lifting - but this is a subtlety in ''all'' of git, so not special here)}}

That branching commit can be seen as the reference to that branch, whether you use the commit ID or the name associated with it ("simply a lightweight movable pointer to one of these commits"[https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell]).

Though in other uses yet - pragmatic ones - a branch specifically points to the ''most recent'' commit within a branch, 
or all commits in that branch ("A branch represents an independent line of development"[https://www.atlassian.com/git/tutorials/using-branches#!branch]). 
It seems the only reason we can say "within a branch" is that that we are consistent about updating what that means.


So a branch can refer to 
: that whole dag subgraph
: the whole line of commits in it (sort of the same thing)
: the commit id or name that defines the subgraph's existence
: the latest state in that subgraph

https://stackoverflow.com/questions/25068543/what-exactly-do-we-mean-by-branch


"That simple?"

Well, things get more interesting in that local and remote branches are not created equal -- or rather, the ''references'' to them are not.

In fact, the terminology around these is also potentially confusing.





"Okay, so is a commit a snapshot of everything, or a branch, or what?"

Is a branch a namespace separate from your main thing, in which commits refer to to only the things you dragged into that branch?

Nope.  A branch is a reference to a commit right along the others, that happens to have a name.
: (But also slightly yes, in that it can help to think as that branch as just the stuff that you altered in it)


'main' is just another branch. It has no special status. 
: ...except maybe to you, "the thing you we try to merge branches back to"



HEAD is also just pointing at some OID.
We can point it at a branch (which we just learned is the lastest commit in a dag subgraph).

 

A lot of this is pretty implicit. 

Say, a branch has its own history not because we keep a history for the branch,
but because at any time we can walk that graph.
: ...backwards, because each commit refers to the ''last'' root tree it is different to (via the OID).

 


If you want to know the model a bit better:

Concepts:
* '''objects''' 
: referred to be OID
: including XXX
: you can fetch contents with cat-file -p <oid>


* '''OID'''
: often shown as a short part of what is actually a longer hash
: git rev-parse <ref>


* '''reference''', often seen as ''refs'''
: named reference
: largely used for branches{{verify}}



Object types include:
* a '''blob''' is a git object that stores file contents

* '''tree'''

* '''commit'''



A commit contains
* a pointer to its root tree
* a pointer to one or more parent commits
* descriptions like author and message

That '''root tree''' will refer to the various directories and files involved via tree and blob objects.  

It is up to the git client to figure out what needs to change in terms of those references, e.g. when you need a new tree object.


This is also how commits are snapshots first, diffs second [https://github.blog/2020-12-17-commits-are-snapshots-not-diffs/]




A branch is nothing more than an OID pointing at a commit. Look at a repository's
 .git/refs/heads/main
This is just an OID, because that's all it needs to be.

And yes, you can get away with 




"Can you have more than one root tree in a repository?"

Yes, but they usually don't.


"Can the same object be referred to from multiple root trees?"

Yes.


"Can you break this graph, can you make it ambiguous?"

Yes, but git tries its best to keep you from doing that.





-->

====History is backwards - on reachability====
<!--
Consider a [[dag]] like: [https://think-like-a-git.net/sections/graph-theory/reachability.html]

      F--G--H
     /
 A--B--C--D--E
        \
         I--J--K  


That's three branches.  
: If you start from E, the history you'll see is A, B, C, D, E.
: If you start from H, the history you'll see is A, B, F, G, H.
: If you start from K, the history you'll see is A, B, C, I, J, K.


Things to note:
* The easiest operation to figure that out is to go from the branch's HEAD, and step backwards.

* no matter which branch you are on, there will always be node that will ''not'' be reachable that way.

Not huge things in themselves, but useful a little little later

https://think-like-a-git.net/sections/graph-theory/reachability.html

-->


<!--

{{zzz|
Since these are all objects, you can ask for their contents - and in the interest of lessening the feelings of magic, let's do that:

For example, if you do something like: {{comment|(note: HEAD could be seen to refer to both its latest commit, in this context the first is effectively a shorthand for the second)}}
 git cat-file -p `git rev-parse HEAD`
 git cat-file -p `git rev-parse HEAD^{commit}`
then you were asking for the last commit, and get something like:
 tree 106eea8f4d4c673ea3e21fa0b3c46d9642557b76
 parent ff1fa1e5127eb8cc6c2285ecfecf868954a39ad4
 author example <example@example.com> 1675265704 +0100
 committer example <example@example.com> 1675265704 +0100

If you want to ask for the 
 git cat-file -p `git rev-parse HEAD^{tree}`
you'll get something like:
 100644 blob 0070dc9e864878b5dff1851c2596931ddb2c2efb    .gitignore
 100644 blob 32d75fa105fcc2f0534028e4fc11626605760398    README.md
 040000 tree 7f3718016ea1c4c13cd90a63eafacce8ea8a0834    src

And yes, 
 git cat-file -p 7f3718016ea1c4c13cd90a63eafacce8ea8a0834 
would just give me another listing like that. (Trees are realized on your filesystem as directories)

And
 git cat-file -p 32d75fa105fcc2f0534028e4fc11626605760398
would give me the contents of that README
}}



-->


====Communication model====

Some people make a point that whereas '''most other source versioning''' only talks via a single central place, like:

[[File:Code_versioning_wc_repo.png]]

...git does not require a central place that everything synchronizes with.

You can synchronize commits with one of any configured remote repositories
[[File:Code_versioning_ad_hoc_git.png]]

Also you can pull from and push to different places, and lots more, which would make that diagram even more complex.


What they don't tell you is that '''we rarely ever do that'''. 
: Ninety percent of the we explicitly all push and pull from the same central repository, so the fact that you don't ''need'' to is usually moot.
: And probably ninety percent of that time, that place is specifically called github or gitlab.

<!--
And, in fact, github specifically avoids using git that way, and goes right back to imitate repository style to keep things simpler, says a ''lot'', and not about git, but about it being a reasonable default and easier to communicate that way.

...which is fully possible, and a few projects intentionally use something like it {{comment|(the hierarchical anarchy of the linux kernel project is a really interesting case)}}, but '''almost nobody else actually does that''' quite like that. 

Most of us use gitlab or github (sometimes a privately hosted repository)
-->

====Model for your local state====

You can think of your own directory you're git-versioning as 
* your local git copy, ''alongside''...
* containing file changes you have not yet added to git

* a [[#staging area|staging area]], so that a commit can be a specific set of changes

* your own [[#HEAD|HEAD]]

* your own [[#On branches|branches]]

* and configured relations to other repositories
:: ''You'' decide 
::: if and when copies relate/communicate
::: which of yor  commits to communicate to others


* all git repositories are created equally
: there is no repository versus working-copy distinction
:: (though things like github ''imitate'' this)
: also meaning all copies have a complete revision history


* Commits 
: think of them not as "the new revision that everyone should have" (as in repo/working copy), but of each commit as a specific annotated collection of differences
: a commit is local unless communicated
: each commit has an id
: each will chain onto a previous commit
:: which a lot of the time makes a straight line (one parent) but occasionally branches (two things have the same parent), and merges (multiple parents)
:: (the structure is a directed acyclic graph)


* you stage a bunch of changes, then commit that ''to your own copy'' (in a single transaction)
: the '''index''' is what you stage to, which you build up interactively


* So you generally have to consider HEAD, the index, and your working directory, and also the stash if you use it


* The previous point is why some commands have more modes than you'ld think
: as an example, {{inlinecode|git reset}} can be used to
:: remove things from being staged
:: remove a last commit from HEAD, but don't touch your files or what is staged
:: remove a last commit from HEAD, and clear what is staged, but don't touch your files 
:: restore working directory to HEAD, losing all local changes
:: restore working directory to HEAD, except if you have uncommitted changes
:: ...which are '''''wildly''''' different things, all of them useful, but you need a presentation or a long think before you understand how exactly



* if you want to communicate such changes between copies, you need to 
** tell git how copies relate             
** explicitly trigger what to communicate

* You can use git much more decentralized if you want, but the "we use this one spot as a repository" is common because it's easier for ''most'' uses
: in which case:
:: git clone will usually make it relate to where you cloned it from
:: after which you can git pull and git push.

===Stuff you should learn better eventually===

====Branching====
<!--

A branch is usually understood as a series of changes with an intent.


You can commit/track them separate to where they came from, but the intent is typically to eventually content-merge back.


Branching in other models are often roughly the same as tags - .



This is also roughly the view that git takes. 

Branches mostly just points to a commit, like any other commit, but this time you also ''named'' it.
{{comment|You technically don't even need to name them, but names are rather useful when you want a "series of changes with an intent" concept, which is what branches typically are.)}}


When you just created a branch, and before committing, the branch points to the same commit as the branch you're branching off (often your main development chain, often called master).

Aby next commit would in the current branch, but really, the branch itself is mostly just a pointer,
and a commit within a branch moves that pointer to the new commit{{verify}}.


Because git is big on thinking about differences in terms of one or more commits, such a branch is easy to use for things like hotfixes: the changes back to when they were merged, in one or more commits.




HEAD is used to refer to the branch you're currently on {{comment|(yes, this is a little different from what HEAD means in other systems)}}.

git checkout changes what branch HEAD points to (also changes the directory to reflect that branch. So checkout and reset can do similar things)



master is usually your main development chain.

The name is just a convention. It has no special status to git among other branches.
You'll spend most of your time with master as the active branch just because that's a sensible way to work.

If you make a new branch ({{inlinecode|git branch ''name''}}), that effectively just means creating a new pointer to whatever is currently HEAD{{verify}}

A commit will go to your currently active branch - because HEAD refers to the most recent commit on that current branch.



''Switching'' branches is done with {{inlinecode|git checkout ''name''}}. 
: Checkout, because what you're asking amounts to making your directory reflect the code state that that branch represents - more specifically the state of the last commit on that branch.
: which is why you'ld often commit or stash before switching


There is also a {{inlinecode|git switch}}, which was added later (alongside restore, which is like-checkout-but-different ''differently'').

Differences include
* switch does ''not'' require a clean index and working tree, checkout does.

* particularly uncareful use of checkout can lead to [[detached head]]


https://www.infoq.com/news/2019/08/git-2-23-switch-restore/





Are branches scary?
* people are someone way of branches - using them too enthusiastically can be troublesome.
:: that seems to be less about fundamental differences, and more about how they are explained - the longer you work on a temporary branch, the more troublesome a merge is. Git just forces you to think about it a bit more, so may make you work in smaller chunks



'''"If a branch switch is also a checkout, can I lose work by switching branches?"'''

No.

You can, if you specify --discard-changes or --merge. 
But you would only do so if it was refusing because you don't have a clean index / have differences to HEAD.

In principle, you cannot switch branches when you have uncommited changes


'''"What gets added to a branch?"''' 




'''"Can I have multiple branches?"'''

Yes, and that is often a useful thing to do.

If you're asking, you're probably asking because you're not sure about how changes are localized to branches.



-->
====Merging====
<!--
When you branch in the sense of "working on a specific thing separate from everything else"

...then you probably want to merge meaning "and now the result of that goes back onto the main thing".


'''Do we want to merge all commits since the divergence --  or just the overall changes?'''

That is a choice.

The default is all commits. This is a "show your work" thing.

The latter option is called a squash(-and-)merge, 
and it can make sense when you know a lot of commits were just messy inbetweens



There is also a rebase merge, which basically just ''replaces'' a line of commits.

Which is mostly what ''just a rebase'' is, without needing to call it a "rebase ''merge''",
and the differences are relatively subtle.


In your own repository, all commits separately makes sense in the 



https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging

-->

=====Squashing/rebasing merges=====

<!--
wishes it addresses:
: reduce a series of related commits into 
: ...when that is useful to someone else
: ...ideally with minimal headache for you


When you want to send things elsewhere (pull/merge resuests),
chances are they have a policy of sending a single commit, not a series of loosely related ones.
Or maybe a single commit per functional change (though often that can be separate pull requests).

Again, mostly for their sanity of putting such changes in and taking them out later.


Even in local teams, 


'[[Feature branches]]' are a (general) recommendation in part because "now collapse what I've been working on into a single commit"
is ''easier to express'', and thereby also less likely to cause you headache.

Also, 
: git merge --squash gives less control and you can't see what you're doing, but may just work
: git rebase -i  gives you an editor which lets you fine-tune. Slower, but you can see what you're doing.


-->

==Introduction by example==


====Client setup (optional)====

Note: You may wish to set how you'll be identified elsewhere: {{comment|(...actually saved in your ~/.gitconfig)}}

 git config --global user.name "My Name"
 git config --global user.email my.name@example.com


There's some other config you may want to play with, like:
 git config --global color.ui true

====Starting to work with versioned code====


Perhaps the simplest way to start is to 
* '''create (or find) a project on github''', and
* '''clone it'''
: implicitly sets up that project as the origin, e.g. for later pulls  (and, if it's yours, also pushes)
 git clone https://github.com/example/test.git


For some local tests, you could '''create a completely blank repository'''
: good for messing around, but you e.g. won't get to test any pushing or pulling until you learn how to set up origins and such. 
 git init


Also keep in mind that if you make a copy of a git directory (including its .git metatada), you get a separate copy you can play around with.
{{comment|(This is also the simple-and-stupid way to make backups)}}



<!--
The origins and remote stuff is the kind of thing you'll want to know eventually, but maybe not on day one.

That said, you ''can'' consider exactly that: the third option here is 
turning the second mentioned option (bare repo) 
into the first option (it connected to github),
because it does feel useful to learn this isn't so scary - it in theory consists of little more than:
 git init
 git remote add origin git@github.com:accountName/projectName.git

...plus the auth necessary to actually push, 
and some details on when you can or should mention specific remote/origin stuff (e.g. git push -u origin master)
-->






<!--
=====Starting projects on github (the hard way)=====
This is more an introduction of how to communicate any two copies -- still using github as an example.


Basically: 
Create a repository locally,
add github as the origin,
do the required security hoop-jumpery,
and push stuff there.


Assuming you've created a git repository for your project folder (you can have code there already, or not) with:
 git init

When you have files to add, stage them:
 git add ''files''

And perhaps check whether you've forgotten anything:
 git status -s

Commit to your (own) repository: {{comment|(-a means 'stage automatically'; you probably want this until you want to stage separate commits using the index)}}
 git commit -a



-->

====Basic staging and commits====
{{stub}}

<!--

In git, commits are a two-step thing:
* you stage things and keep 
* you commit that

This makes it a little more fine-grained than "just make the tracked version just like mine" - it lets you e.g. do partial changes,
and makes it easier to have a commit be a coherent sets of changes, including partial changes.


The larger the team, the more useful this is, because it lets you review and revert changes.

In something like subversion, you would probably require people to collect such changes in a branch.

Git use also encourages using [[feature branches]], but in smaller cases you can collect specific changes is plain commits.


In the immediate sense you stage things to ''possibly'' commit, 
then you commit to 




Staging changes:
 git add .
    
 git reset -- path/to/file  # remove file from being staged 

 git rm file 
 git mv file

 git status	      # summary of unstaged and staged differences
 
 git diff             # unstaged differences: differences between files and index
 git diff --staged    # staged differences: difference between index and stage
 
 git commit           # commit staged differences


What others call update from repository, git calls pull. Which only makes sense after it's got somewhere to fetch from:
 git clone url
 git pull


* when working in a repository style, you'll also want to get changes before a push
: {{inlinecode|git pull}}, which amounts to 
:: {{inlinecode|git fetch}}
:: {{inlinecode|git merge FETCH_HEAD)}}




Diffs
 git diff [rev [path]]





Remove things from staging:




-->


=====Undoing things=====

See a few commands in the conflict resolution below

<!--

Undo a stage

* Undo a git add - a.k.a. undo a stage, remove it from the index, but don't touch the local file 
: after the next commit HEAD will contain what was on HEAD before, and you will not
 git reset <file> 

: ....which will not work for the first commit in a repo. You can then use git rm --cached ''file''. If this was the first inclusion of the file, it has the same effect (file won't exist), but if it did exist it will be removed from the next snapshot.


https://stackoverflow.com/questions/5798930/git-rm-cached-x-vs-git-reset-head-x


-->

=====Inspecting local state (staged, committed but not pushed, stashed)=====
<!--
(remember that HEAD is the latest (locally known) commit on this branch)


The changes that committing the currently staged things would make to the repo state  (difference between index and HEAD)
 git diff --cached

The difference you have staged (its differences to your working tree)
 git diff

all differences between working tree and repository (unstaged and staged)
 git diff HEAD



commited but unpushed (assuming that your branch is called {{inlinecode|main}})
 git log --stat origin/main..HEAD
 git diff origin/main..HEAD



Stashed:
 git stash list

-->

====Inspecting some stuff====
<!--
'''Inspecting'''

See recent changes, e.g. date:
 git log


Show origin URL:
 # brief
 git remote -v
 git ls-remote --get-url 
 git config --get remote.origin.url # previous line preferred?
 
 # more about remote branches
 git remote show origin


Unsorted:
 git describe   # "Describe a commit using the most recent tag reachable from it"
 git rev-parse HEAD


See also:
* https://github.com/gitbits/git-info



-->

====Communication====
<!--

Keep in mind that since all copies are created equal, and only some are set up for remote access, you'll typically push your changes to a common point of exchange, and pull other people's changes from there. 

{{comment|(yes, these are comparable to commit and update in the repository/working-copy setup. Since git does versioning locally, the communication elsewhere is a separate concept. You ''could'' say that pushing is committing elsewhere, and pulling is updating from elsewhere)}}




Assuming you have created a repository:
 touch README.md
 git init
 git add README.md
 git commit -m "first commit"


{{inlinecode|git remote}} manages the set of related repositories.
Say you want to store your stuff on a newly created github project. You'ld probably do something like:
 git remote add origin https://github.com/''username''/''projectname''.git

It seems that calling something <tt>origin</tt> seems to be nothing more than a convention.{{verify}}


See also:
* https://www.kernel.org/pub/software/scm/git/docs/git-remote.html

-->

=====Interacting with connected repos=====

<!--
...in particular those that you have write access to.


To continue the 'stuff goes to github' example above, you'ld probably then do: [http://gitref.org/remotes/#push]
 git push -u origin master

Notes:
* <tt>master</tt> is the default branch name (the local one)
* <tt>-u</tt> means 'remember this', meaning that you can type just {{inlinecode|git push}} from now on.
* the syntax is <tt>git push [repo [refspec]]</tt> - see also [[#refspecs|refspecs]]




And, after others have made changes, you can fetch them:
 git pull origin master

Actually, on larger projects you may wish to <tt>fetch</tt> instead. 
A pull is a combination of fetchign changes and attempting to merge with the current branch
 git pull [repo [refspec]]


Fetching[http://gitref.org/remotes/#fetch] on the other hand doesn't merge yet, which means you can inspect the differences.
 git fetch [repo [refspec]]

-->



'''[[Pull requests]]''' basically mean you saying "hey collaborator, I've completed adding this feature to your code, might you want to integrate it?".

Pull requests aren't really a git concept, they're added by git hosters.

And they make more sense to do with such a more centralized place, than with a "everyone has their own copy" variant, if only because of the amount of confusion involved.



=====Branches and communication=====
<!--

* Your interactions are pulls and/or pushes
** Push:
*** take what is in your copy and push it to a remote copy.
*** Refer to local changes, and a branch in the remote copy
*** may well create a branch on the remote end.
** Pull:
*** Essentially {{inlinecode|git fetch}} + {{inlinecode|git merge}}:
**** Fetch: fetch ''all'' changesets and pointers from another copy
**** merge: try to merge ''all'' those changes to your copy




See also - introductions:
* http://reinout.vanrees.org/weblog/2011/10/04/github.html
* http://tom.preston-werner.com/2009/05/19/the-git-parable.html


See also - discussion of uses:
* http://nvie.com/posts/a-successful-git-branching-model/




In git it's basically a complete state (references to content) plus a note that it was based on a specific previous state. More techically, it's


: If you branch a lot, you may want a good naming system.



References can be kept very simple, almost to the point where you don't need to know about them.

They become useful when you want, say, selective fetching of branches.


'''Refspecs''' are the things in the form <src>:<dst>, where 
<src> is the pattern for references on the remote side
<dst> is where those references will be written locally

The + tells Git to update the reference even if it isn’t a fast-forward.



When instead of:
 git pull origin
you do
 git pull origin remotename:localname
...you're telling it to make a local branch called localname, from the remote branch named remotename



http://git-scm.com/book/ch9-5.html



-->

=====Tags=====
<!--

Like in most other content versioning, tags refer to a specific version of the whole.

Such stable references are e.g. useful for specific releases.



A '''lightweight tag''' is a pointer to a specific commit, so basically refers to an unchanging state of the whole (/branch?).
: technically, it's little more than a commit checksum

An ''annotated tag''' isn't a reference but a full object, including checksum, tagger name, email, date, and message, and optionally GPG-signed 


By default, tags are ''not'' transferred implicitly, you can do so explicitly with git push origin tagname


https://git-scm.com/book/en/v2/Git-Basics-Tagging

https://git-scm.com/docs/git-tag

-->

=====On using someone's existing branches=====
<!--
When a repository branches, it's often things like mainline and betas, or such.

View branches known in the current copy
 git branch -a

Switch to one:
 git checkout branchname


And when someone actively works on it, make sure we have everything for from its origin:
 git pull
-->


=====Pull requests / Merge requests=====
<!--

[[Pull requests]]

-->

=====Branching for cooperation=====

<!--
: '''if you're planning to merge it locally'''
...in other words, if you don't want to do it in your main branch, e.g. because you may wish to give up and throw these changes away later.


Think of a name, create a branch with it:
 git branch ''cleanup''


A branch is basically a named state of the code, so to work on it it needs to be current. Switch to it:
 git checkout ''cleanup''

Now say you staged all the changes you want to make, and finally want to commit it
 git commit -m ''cleanup, within a branch''


If you just want its changes to be permanent, you can switch back to your master branch, and merge the cleanup branch into it:
 git checkout master
 git merge cleanup
...after which any of your pushes would include these changes.

The branch itself (as in context you made these changes in) still exists, and you can remove it:
 git branch -d cleanup


http://stackoverflow.com/questions/2342821/git-branch-deletion
-->


: '''shared branches'''
<!--
Say you have experimental code, and you want someone else to see it, or work on it too.

Make it
 git branch ''cleanup''

It's probably useful to make sure it exists on the remote end
 git push origin splodeyfeature


tracking a branch



you might want to keep it when (?)


Doing branch-and-berge stuff on a single local copy makes limited sense, but it's a good idea if you 

-->


==Conflict handling==

<!--
 Updates were rejected because the remote contains work that you do
 not have locally. This is usually caused by another repository pushing
 to the same ref. You may want to first integrate the remote changes
 (e.g., 'git pull ...') before pushing again.
 hint: See the 'Note about fast-forwards' in 'git push --help' for details.
-->


====Specifying commits and ranges====
<!--
: by hash
: HEAD~ is the parent of head, as is HEAD~1


In other contexts you may want ranges, e.g. HEAD~5..HEAD meaning the changes in the last five commits
-->


====Resolving conflicts (also: undoing things)====

<!--

restore and reset

: remove a last commit from HEAD, but don't touch your files or what is staged

: remove a last commit from HEAD, and clear what is staged, but don't touch your files 

: restore working directory to HEAD, losing all local changes

: restore working directory to HEAD, except if you have uncommitted changes

: which are wildly different things, all useful, but you need a presentation or a long think before you understand how exactly



If you specify a particular commit 



https://git-scm.com/book/en/v2/Git-Basics-Undoing-Things


https://web.archive.org/web/20200216073524/http://justcode.me/git/undo-git-commits/


https://devconnected.com/how-to-undo-last-git-commit/



----

Some terms
* working tree - state of your source code on disk




Even just "I didn't mean to stage that" (which is ''correct'' gittish behaviour, 
in terms of organizing things into bite sized commits) needs a deep dive on "how to undo"
because there's many commands that almost do what you wanted but are all subtly different 
: and I really would like to know which ones ''don't'' wipe my day's work without me having to make a manual backup just in case I needed to do ''even more reading''.

Yeah, git has a reputation of being unforgiving about mistakes made by mere mortals.





Note that undoing things is sometimes a ''way'' to resolve conflicts, 
e.g. when you have a pull, that conflict with local changes, and you decide your changes can be thrown away.


'''Throwing away file changes'''

* '''You made local changes, that not yet staged/committed, ''and'' you want to remove those local changes'''
: note that 
 git checkout -- filename
: effectively means "makes the state the current committed HEAD". Except checkout may do a lot more than that, so git later added:
 git restore ''filename''
: ...seemingly to e.g. separate out the branch-switch  (it introduced git-switch at the same time)



* '''You made local changes, in commits, that you want to throw away'''
 git reset
:: discard commits
:: clears uncommitted changes
: BE CAREFUL: git reset serves a few distinct purposes



'''Not throwing away file changes'''

Current state: Your copy has changes committed to a commit
Wanted state:  Those changes should become uncommitted file changes again




* '''You staged more than intended - you want to undo the add, but don't touch the file (you probably want it in a different commit)'''
 git restore --staged ''filename''
: BE CAREFUL: though - without the --stage it



* '''You made local changes - that you do not want to commit now, do want to keep , but not yet
: often because they conflict with a pull
: You can postpone your own issues with:
 git stash
: You can also branch, but that's more work unless you already know you want to start something like a [[feature branch]] for this anyway


* You made local changes - that you want to put in a different branch
 git branch



* you committed changes, that you want to undo the effects of
 git revert ''commithash''
: adds a new commit with changes that amount to undoing what the last commit changed
: both these changes will still be recorded


* you committed changes, but you would conflict with a remote copy, so ''for now'' you want to undo that commit to be able to push the rest
: the best solution is still the previous{{verify}}



----

* git add
: basically because it tells git you want you keep your local changes, and that you want it to figure out 



https://git-scm.com/book/en/v2/Git-Basics-Undoing-Things



"The following untracked working tree files would be overwritten by merge:"

A file that's newly coming in via an update
already exists in your local copy but isn't tracked in your copy.

git basically tells you to figure out why (even if that file is identical to the one coming in)

Often enough you want to give your untracked file another name to figure out how to merge it into the tracked one. Or sometimes remove it.

-->


=====stashing=====
<!--



Lets you have local changes, but set them aside.

Mostly useful to postpone a decision about specific file differences.

Useful when you're not ready to commit them, but also don't want to wipe them completely, 
and e.g. want to work on another branch for now.


You can also stash ''part'' of the changes to a file (see -p for partial stashes)


(It seems like this is actually a commit, but to a place that is not reachable from any branch, just from its own stashy name.{{verify}})



To that end:
 git stash save
does two things:
* saves any changes to the stash, 
* and reverts the working directory files involved to the state they had at the last commit{{verify}}



Inspecting the stash:
 git stash show     # shows the files involved
 git stash list     # lists the names you'll need to refer to stashes
 git stash show -p  # show differences as a diff

Using stash contents:
 git stash pop STASH-NAME                 # apply changes from stash to files, and remove the stash
 
 git stash apply STASH-NAME               # apply changes from stash to files, and don't remove
 
 git stash branch BRANCH-NAME STASH-NAME  # put on its own branch, useful when apply has conflicts



Removing
 git stash drop STASH-NAME   # remove a specific stash (assuming you have more than one)
 git stash clear             # just remove all

-->


===="You have not concluded your merge (MERGE_HEAD exists)."====
<!--
If this surprises you, then probably, ''some'' pull tried and failed to merge automatically.

That merge is marked as your problem, so you need to finish it, or reset it, before another pull could happen.

git merge --abort (or git reset --merge before 1.7.4)
-->

====CONFLICT (rename/delete)====

e.g. deleted in HEAD, but locally renamed to something else


====Your branch and 'origin/main' have diverged, and have 4 and 5 different commits each, respectively====
<!--
Two people had a copy with the same HEAD, and did a bunch off commits
(often but not necessarily on the same branch). 


"I want to keep both changes"
 git pull --rebase
Rebase is a ''specific'' way to resolve this. 
: In theory, you could plan for a merge commit, probably figuring out what changes to apply to remote changes, as to apply your changes after it.
: A rebase rewrites the history with new commits (here since the point of divergence)

Why care about the difference?

If you ''plan'' rebases, it's often to have it appear like a cleaner, flatter/linear project history.





"I don't care about those other changes, I want MINE"
 git push --force

"I don't care about ''my'' changes, I want to update to the repository"
 git reset --hard origin/main    # or whatever you mean to

-->

=====....but the commit history is identical=====
<!--

(why)
https://stackoverflow.com/questions/2298556/branches-have-apparently-diverged-but-commit-history-is-identical

You probably need to 
 git remote update 

...which, note is different from a git pull ''or'' git update, in that 
* git remote update will update ''all'' branches, but not merge any changes in. (pedantically: all branches that are set to track remotes)
* git update        will update the current branch, but not merge any changes in.
* git pull          is an update ''and'' a merge of the current branch

git fetch will update only the branch you're on, but not merge any changes in.

git pull will update and merge any remote changes of the current branch you're on. This would be the one you use to update a local branch.

-->



====More regular====

====="Your local changes to the following files would be overwritten by merge"=====

You have changed a file.
: which is a difference to remote copy

Someone else changed that file too
: which they committed and pushed (to what you consider remote HEAD)

You are pulling their changes.


That pull wants to update a file (remember, pull = fetch + merge).

A file you have changed, and specifically in the same areas, so it cannot be merged automatically. 

So that's a conflict, in that you probably don't want it to overwrite what you have done.

<!--

If you care about your changes, but not yet, you can make them ''not'' involved in this pull like:
 git stash
 git pull
 git stash pop


If you care to merge your changes, you can make those changes relevant to a merge like:
 git add
 git commit
 git pull
...which effectively involves them in a merge, after which you can push


If you do not care about local changes, you can throw them away:
 git reset -- hard
 git pull
-->


<!--

'''Seeing the difference'''
 TODO

Yes, <tt>git diff</tt>, but there are two things to not forget
* git diff compares to HEAD{{verify}} - the latest you know, ''not'' the remote we're talking about
* Note there technically can be a difference between the staged changes, and the file currently on disk.
:: --cached picks the one in the index, without it you would pick it from disk

But what you ''probably'' wanted to do is something like:
 git diff origin ''filename''
: (this requires a git fetch origin, but if you got that error, you already have. Perhaps consider doing a fetch before/instead of a pull if you expect such things)
: often with a /main ?



'''Recourses'''

From the [[#Undoing_things]] section:

* Do you want to postpone thinking about your changes?  Stash them:
 git stash filename


* you want to throw away local changes that you had not added/committed yet
 git checkout filename    # for a specific file
 git checkout             # for everything - be careful


* you want to throw away changes in commits {{verify}}
 git reset 
:: discard commits you haven't pushed yet{{verify}}
:: clears uncommitted changes{{verify}}

* you committed changes, that you want to undo {{verify}}
 git revert 
: adds a commit that undoes the current commit


* You made local changes - that you want to put in a different branch
 git branch
: assuming you want to merge that, this really only postpones the issue


https://git-scm.com/book/en/v2/Git-Basics-Undoing-Things

-->

====="Updates were rejected because the remote contains work that you do not have locally"=====

<!--
Like the rest of the message says, this often comes from you trying to committing to a ref that has already been committed to so is no longer HEAD.
While you could branch in theory, what you usually want to do is pull  (fetch+merge) those changes so you commit your changes on top of those existing changes.
-->



=====Your branch is behind 'origin/master' by 8 commits, and can be fast-forwarded=====

<!--
Often comes before more complex messages, 
''but'' by itself is actually indicating where there is no issue{{verify}}

You would often want to see what the



-->

====error: You have not concluded your merge (MERGE_HEAD exists)====

The previous pull needed to merge, tried to merge, and failed to do so.

There are multiple reasons you can get into that situation, and the best fix will vary along.

====Your configuration specifies to merge with the ref 'refs/heads/master' from the remote, but no such ref was fetched====

Seems to mean that that ref doesn't exist - anymore, or never did.


Chances are this came from a {{inlinecode|git pull}}, which you'll remember is effectively a {{inlinecode|git fetch}} plus {{inlinecode|git merge}}, 
and it is the latter that complains.

(not that a git merge gives the same error, but hey...)

<!--
merge: refs/remotes/origin/master - not something we can merge
-->

===Other messages and errors===
====fatal: detected dubious ownership in repository====

Some files are owned by other users, e.g. root, which is ''potentially'' security-relevant. 
{{comment|(That is, if you share storage with untrusted users, them editing your .git/ can be Bad)}}


Apparently it won't tell you what it saw, though.

Which is probably why the suggested fix is "no just trust it, and ignore this security warning",
but it's probably a good idea to actually look at the ownership first.


Options
* change ownership, often something like
 chown username:groupname /path/to/dir -R
* say you don't care
 git config --global --add safe.directory /path/to/dir


====You are in detached HEAD state (and: what is HEAD)====

<!--
Note: This is informational advice, not an error. 

At the same time, '''unless you did that for a specific reason''', 
detached head is not what you want because it will ''soon'' be a problem.


In that detached HEAD state ''means'' you do are not currently on a branch.

...and since most regular use of git is add to a branch, being on a branch to add to is... very typical.


''Not'' committing onto on a branch's HEAD is something you only want to do knowingly and on purpose.




For context: '''"What is HEAD?"'''

HEAD has some weird details actually, but you can ignore most of those weird details most of the time.

The main confusion is probably that even in everyday use, HEAD has two or three ''common'' meanings:
* HEAD being the concept of the latest commit in any branch
:: e.g. pointing out that each branch has its own HEAD

* HEAD as pointing to the HEAD of the ''currently set'' branch  
:: this is arguably the most important one, because most of the times you care just about the branch you are working on

* HEAD as a temporary state in merges the last commit you checked out
:: (usually that of the last commit (if ), sometimes of a specific commit (in detached HEAD state))

Sometimes these meanings are the same for your intents and purposes. Sometimes not.



If considering different revision systems, HEAD most often means "the thing your changes will be relative to".

...but ''that'' breeds different intuitions depending on the nature of the revision system. Consider:
: where the repository (not the working copy) is right now
:: ...which might change without our help
: the revision you checked out -- i.e. the working copy, not the repository (I believe this is a wrong intuition)
: the state you are working on - in the sense of the thing your changes will be relative to{{verify}}.
: the commit/rev your next changes will commit relative to


In the real world, consider that each git repo can have different branches. 
Each branch is basically just one of these ''latest'' points.
When anyone adds new code, you want it to keep pointing to a new latest latest version.

Intenally, each such HEAD represents an extra bit of repo-side management like that.

To you, at a place in time, it will refer to a certain commit.



You will see definitions like "it is the latest commit on your currently checked-out branch",
and even more pragmatic ones that it ''is'' the currently selected branch.

The two are equivalent, by definition, because whatever commit the branch HEAD points to '''''defines''''' what gets interpreted when you use that branch by name.



But also, every repo copy has {{inlinecode|git show HEAD}}, based on .git/HEAD



{{zzz|Technically, HEAD only ''usually'' points to a branch name, in that your {{inlinecode|.git/HEAD}} will either:
* points to the name of a branch
* (or to a commit ID, but that means you are in detached HEAD state)
}}


* {{inlinecode|git show HEAD}} is the current commit you have checked out
:: resolved to a commit id, via .git/HEAD 


: Note that .git/HEAD contains something like refs/heads/main which is basically just a path - that points to .git/refs/heads/main



Ir might be that:
 # cat .git/HEAD
 ref: refs/heads/main
which then implies that branch's latest commit, e.g.
 git show-ref    # ...among other things prints...
 dce2e3f2bbc9c0e38a994bedf3e941544a103807 refs/heads/main
and in the same state, the first shown item in the log (the latest commit):
 # git log 
 commit dce2e3f2bbc9c0e38a994bedf3e941544a103807 (HEAD -> main, origin/main, origin/HEAD)
 Author: me <me@example.org>
 Date:   Sat Oct 28 22:50:34 2023 +0200
  
    first version of blabla
In this case, when you add a commit, HEAD does not ''technically'' change, in that it keeps pointing to refs/heads/main,
but the node that that refers to would be updated to point to the new commit.


All good and regular, 
yet '''you ''can'' also make HEAD point to a specific commit'''.

Which means you can have your (local) HEAD point to a commit that is ''not'' the latest in its branch.


So no, a ''repository'' does not really have a HEAD. A branch does. 
(unless there is just one branch, and git people will laugh at you if you do that, because branching is ingrained into git more than it is in others).




Why would you make it point to a specific commit?

Well, it's a ''side effect'' of checking out a specific commit, like
 git checkout 87ec91d

You would typically only do that to specifically get an earlier state (not strange to do e.g. when you are looking for the last version that built fine) - yet now 
: the actual branch refers to a later commit
: you've pointed HEAD at an earlier commit.

If this is only to ''look'' at it, this is a feature. 
But when you want to continue work, then 

In fact, CLI git will tell you that:
 You are in 'detached HEAD' state. You can look around, make experimental
 changes and commit them, and you can discard any commits you make in this
 state without impacting any branches by switching back to a branch.
 
 If you want to create a new branch to retain commits you create, you may
 do so (now or later) by using -c with the switch command. Example:



So git knows you have pointed HEAD at something that isn't the latest branch state,
and is telling you about it because chances are you don't want to commit relative to that.


If you ''did'' want to go back versions and create a new branch from that point, 
 git branch newbranch   # only creates that branch, and you probably also want:
 git checkout newbranch # to point HEAD to this

If you only wanted to look at an earlier version for a moment,
you can switch back to the end of (what happens to be the same) branch:
 git checkout ''mybranch''



https://www.cloudbees.com/blog/git-detached-head

https://jvns.ca/blog/2024/03/08/how-head-works-in-git/

-->

====This repository moved. Please use the new location====

This is github informally telling you that the repo was probably renamed, it's resolving that for you, but you may want to change what you're referring to.

You probably want to do: 
 git remote set-url origin 'new_url'

===Altering history (and potentially creating bigger problems)===

<!--
((squash merge?))





https://stackoverflow.com/questions/307828/how-do-you-fix-a-bad-merge-and-replay-your-good-commits-onto-a-fixed-merge

====quick fixes to recent files: git commit --amend====

Modifies the most recent commit (and ''only'' the most recent commit) without changing the reference/snapshot.

Amended commits seem to amount to removing the commit you are amending from the current branch.


It's perfectly fine to do on changes you haven't pushed elsewhere,
but a '''bad idea to do to a commit you have made public''',
because when other people have their own commits relative to it,
this is a conflict that is ''messy'' to resolve.



Scenarios where this is useful:
* alter the commit message, without changing the contents, e.g.
 git commit --amend -m "A better message"

* adding a file we forgot to add to what to you is one logical change (no change to message)
 git add main.py 
 git commit --amend --no-edit



====changes to older commits: git rebase====

If you squint, rebase is amend but more so: you are shoving ''multiple'' commits out of your branch
and replacing them with your own.

Like amend, the original commit still exists in the repo (and you can find them with the reflog),
it's just no longer considered part of your current branch.

Again, this is a '''bad idea to do to do to commits you have made public''',
in that you can create a very messy conflict.


https://www.atlassian.com/git/tutorials/rewriting-history



====removing files from all commits they are involved in====

This amounts to the above but ''even more so''.

And, ''fundamentally'', can cause even more problems in cooperation.



{{inlinecode|git filter-branch}} basically applies a change to all commits.
So instead of 
 git rm -r --cached password.txt
you run 
 git filter-branch --index-filter "git rm -rf --cached --ignore-unmatch password.txt" HEAD

(does this actually remove things from the copy and reflog on the next pull? probably not?)

Notes:
* "Commits that are empty afterwards (because they only changed the Rakefile) are removed entirely"
: https://stackoverflow.com/questions/2004024/how-to-permanently-delete-a-file-stored-in-git
* can be very slow 
* can put your repo in a very messy state



'''BFG Repo Cleaner''' is a third party tool that 


'''filter-repo''' is a third party tool that 


https://github.com/newren/git-filter-repo




-->

==Other notes==

===Credential stuff===

====Credential management====
{{stub}}

<!--
https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage

https://git-scm.com/docs/git-credential-store


'''Always there, part of git'''
* store (git-credential-store)
: stores in plain text

* cache (git-credential-cache)
: puts it in memory temprarily


'''OS-specific''' (should be there in)
* git-credential-osxkeychain - macOS keychain
* git-credential-libsecret - GNOME Keyring, KDE Wallet
* git-credential-wincred - Windows Credential Manager


'''Software specific'''
* git-credential-gopass: stores in gopass
* git-credential-lastpass: stores in LastPass
* git-credential-1password: stores in 1Password
* git-credential-keepassxc: stores in KeePassXC

'''Service specific'''
* git-credential-oauth (cross platform)
* git-credential-netlify - Netlify.
* git-credential-azure - Azure 


https://git-scm.com/doc/credential-helpers

-->


====github personal access tokens====

A few years ago, github stopped allowing passwords in credentials.

It wants you to use access tokens, which are a mix of 
* a longer password
* each (yourusername,atoken) pair 
:: can be associated with its own rights
:: can have its own expiry


As https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens explains, generating a token is done at:
 Settings &rarr; Developer settings &rarr; Personal Access Tokens &rarr; Fine-grained tokens


Criticism #1: this is coarse grained, mostly allowing "write to all my repos"


Criticism #2: It does not explain how to actually use it.
: sort of makes sense, in that each client does it its own way -- including how it prefers to store the credentials
: but some instructions for common clients would have been nice



<!--
TODO: various methods

* clone with 
: just a git clone URL may not ask

* alter the origin, like
 git remote remove origin
 git remote add origin https://<TOKEN>@github.com/<USERNAME>/<REPO>.git
...and you might 
 # you could figure out the current one like:
 git remote get-url --all origin
 # https://github.com/username/reponame.git

 # https://github.com/scarfboy/everyday-admin.git

git remote add origin https://<TOKEN>@github.com/<USERNAME>/<REPO>.git
-->

===Semi-sorted===



====Objects on disk, packfiles, backup, and cleanup====
<!--

At first, each object is its own file, organized by content hash.
While this relies on the filesystem as a database, which is not ideal,
it scales reasonably well.

Once your copy grows ''huge'', though, you will start caring about
* speed
* cleanup
* backup


tl;dr: 
* most repositories are too small to worry about this ''at all''

* if you care most about disk use, 
:: do regular git gc
:: (probably avoid git gc -aggressive until you can actively explain why you ''need'' it)

* if you care about backup first, disk size second
:: use .keep and pack.packSizeLimit ?

* if you care about backup first, disk size not at all
:: consider keeping the objects-are-files system by disabling packfiles (maybe even git unpack-objects, if you already had packfiles)



Apparently 
* git-gc is auto-run every n commits{{verify}}

* git-gc will run git-repack

* objects will be packed...
:: when there are as many as as configured by [https://git-scm.com/docs/git-gc#Documentation/git-gc.txt-gcauto gc.auto] (default is 6700)

* gc will re-pack ('consolidate') pack files
:: when there are as many packs as configured by [https://git-scm.com/docs/git-gc#Documentation/git-gc.txt-gcautoPackLimit gc.autoPackLimit] (default 50)
:: unless existing packs are marked with .keep

* there is also a {{inlinecode|git gc --auto}} 
:: "do nothing except if we just crossed a nontrivial amount of bookkeeping to do" (see also gc.auto, gc.autoPackLimit, and more)
:: but which tries to avoid doing complex work{{verify}}
:: some git operations will run this automatically
:: https://git-scm.com/docs/git-gc#Documentation/git-gc.txt---auto




'''On pack files''' (if we ignore backup considerations)

Objects could all be stored separately (in {{inlinecode|.git/objects/pack/[0-9a-f][0-9a-f]/}}).

Packfiles (in {{inlinecode|.git/objects/pack/}}) store a set of objects in a single file. 

They are entirely optional to use, 
but you may want them once you have a ''lot'' of objects.


Packfiles are compressed, and can be told to creatively look for differences ''beyond'' direct diffs,
and in fact chains of differences{{verify}} if that compresses better, which both saves more disk space,
at the cost of operations involving those chains taking longer.


Notes:
* It's often reasonable to use packfiles, if only because the older, rarely-accessed stuff will go there

* At the same time, packfiles aren't always better, and sometmies config may becomes an informed balance of choices.


* Compression is typically worth it.

* Short chains are typically worth it, longer ones are a tradeoff with diminishing returns.




'''What can/should I do on the regular?'''

Most people seem to look to
* {{inlinecode|git gc}} 
** removes objects you no longer need (which, depending on your habits, may ''never'' happen)
** may/will also run 
*** git prune [https://git-scm.com/docs/git-prune]
*** git repack [https://git-scm.com/docs/git-repack] (specifically git repack --cruft ?{{verify}})
*** git pack
*** git rerere [https://git-scm.com/book/en/v2/Git-Tools-Rerere]


* {{inlinecode|git repack}}
:: adds unpacked objects to a pack, tries to do clever delta-chain stuff while doing so
:: often {{inlinecode|git repack -A -d}} roughly meaning 'put into single pack and remove some loose stuff'{{verify}}
::: {{comment|(or -a -d; the difference lies in "if objects no longer have a reason to be in a pack, keep them as just objects")}}


git repack -Ad ; git gc




'''What about {{inlinecode|git gc aggressive}}?'''

{{inlinecode|git gc aggressive}} seems to be more about ''redoing'' delta decisions,
{{comment|(as such, git gc --aggressive is actually fairly similar to git repack -a -d{{verify}})}}
and less about aggressive delta-chaining ''unless you specifically tell it to''; 
its defaults are actually more everyday-sensible than aggressive.

Doing this once in a blue moon may reduce size -- but it rewrites things entirely,
so defeats incremental backups.



If you want to say "I know I have made bad packing mistakes just now and want to reduce disk size",
e.g. you've used git fast-import, or otherwise imported an large and complex history, 
have just converted a history from another repo format, git repack -a -d --depth=250 --window=250


If you have imported a really involved history, or just ''converted'' a history from another repo, you want to say  and consider:
: higher depth saves more disk, at the cost of future operation speed[https://stackoverflow.com/questions/28720151/git-gc-aggressive-vs-git-repack] and 250 is probably too much (comes from a linus post pointing out a "past me has made bad decisions" case; the default depth is 50)







'''Would you rather have more incremental packs, or a single pack?'''

If your backup is done with a rolling-change thing like [[rsync]], 
then you might save some transfer and writing using 

That said, git seems very good at breaking the concept of incremental backup of these files,
unless you add .keep files, which tell it to keep that pack file as-is
and store things as deltas against it.




'''On backup'''

Git itself is not backup.

If you are never more than a little away from a remote that you consider a central repo, which someone else is backing up properly, you can ignore this.

If you have a local-only repo, or often carry significant changes, or are the sod keeping that central-repo-like copy, you care about backup.



In theory, all separate objects are the easiest to apply [[incremental backup]] / efficient filesystem snapshots to,
so for smaller repos, you might consider disabling pack files.

But for a large enough repo, the size and sheer amount may push you to packfiles.

Annoyingly, '''packfiles, repacking and gc defeat incremental stuff''', 
unless very specific specific care is taken. (git apparently considers this to be a non-issue, or just ''your problem'')


But, as the [https://git-scm.com/docs/git-repack/ git repack documentation] mentions,
''"users fetching over dumb protocols will have to fetch the whole new pack in order to get any contained object, no matter how many other objects in that pack they already have locally"'', which also applies to backup by rsync or time machine or whatnot.





'''Doesn't git bundle help?'''

For certain definitions of help, yes.

Bundles are intended as 'transfer repo contents in a file' uses.

In theory, they can be used as full backup, or even as incremental backups.

The thing is that you do have to do the work.
If your backup solution was rsync or time machine, this is work to set up and work to check (because back up you don't check isn't backup at all), and work to do at restore time. Maybe you find out you only bundled one branch, and have now lost everything else. Fun!





'''You may not need gc'''

Repos with ''only'' code, on personal scale or small-team scale, will probably only touch megabytes of code per year.

Unless you are regularly committing very large files, or frequently orphaning things, 
or are microsoft or the linux kernel project, you can even consider disabling gc (git config gc.auto 0),
and possibly even minimize packing.

It's also a simpler way of getting backup.

And if you're a power user who ''likes'' things like detached commits[https://donatstudios.com/yagni-git-gc],
gc defeats that.


-->

====bundles====
<!--

The idea behind bundles are to make a file with all data required to reproduce, well, whatever you told it to bundle.
 git bundle create repo.bundle HEAD master
 
 git bundle create repo.bundle --branches --tags 
 
 git bundle create increment.bundle 1234567..main



Note that since clone is just init and fetch, and fetch (and anything else that takes a repo url) can read bundles, you can clone from a bundle file.


(--all isn't in the docs?)


Bundles can also be a means of backup -- but as with any backup, backup that you don't test isn't backup at all.

In theory it can even be a means of ''incremental'' backup, '''if''' 
* you remembered what you put in the last one
* you are putting that towards a repo you are ''never'' changing in any other way
...which are pretty big ifs, and you better not get anything wrong.


-->

====git is a great drive corruption detection tool====
<!--
A respository is a database of sorts.
More specifically, it is a content-addressed directed acyclic graphs.



"If you lose one object, what does that mean?"

In principle, everything object downstream from that - everything later (branches, tags, trees) that refers eventually back to this one, will be broken, effectively lost.


If you use the delta compression within pack files (they cannot cross packfiles, though references can),
this effectively introduces references across branches. 

Internal only, not commit-wise, 
but in the "everything that refers back to something broken" sense,
it means corruptions happen laterally.

-->

===="Your configuration specifies to merge with the ref 'refs/heads/master' from the remote, but no such ref was fetched."====

{{stub}}

Lemme guess, github user?

Specifically, you just created a new repo on github, just cloned it, and thought you could fetch/pull from it?

If so, the simplest fix is probably to remove your clone, and clone it again.


'''"Wait what. Why."'''

What that error means is that the remote that you call origin does not have a branch with that name.

In general practice, this error ''often'' means that someone else removed the branch it names
{{(because the likely reason your copy points at something is that that ''used'' to exist)}}.


"Why would there be a branch called 'master'?"
: because [https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell The default branch name in git is master]


"Why isn't there now?" 
: because many public git hosts moved to naming their main branch 'main' and not 'master'[https://github.com/github/renaming for reasons not really relevant right now].

So the repo copy that that clone made was correct ''at that time''.
Yet after you created a repo, it instructed you to do something like:
 git branch -M main
Where [https://git-scm.com/docs/git-branch#Documentation/git-branch.txt--M -M is --move --force], i.e. a branch rename, i.e. move your current branch onto a new branch called 'main'.


"But I ignored that instruction, I didn't do that"

Yeah. But you did one of the things on that page, like add a README via the site, figuring that would be useful.

Soooooo it turns out that implied that github did a branch rename without telling you.

Surprise!

Which means your original clone is now pointed at something that doesn't exist,
and you need to do some git gymnastics to point it to the right branch.

It's just easier to remove it and clone it again.




====Backup====

<!--
Git is ''not'' backup.

It does ''not'' keep everything you ever gave it -- there are several ways to remove things permanently.


Git is effectively a complex database.

So file-level backups are likely to give you a bad state, unless you disable pushes during backup. 


Git can also completely rewrite files (even without git repack).

This basically means that incremental backup will (to save storage, or transfer, or time) is basically already defeated.

It's also why you wouldn't want it network-mapped in everyday use.



An LVM snapshot should probably do.



git clone sounds simple, but will not be a 1:1 copy, 
: --mirror
: ignores stashes



git bundle

: can be incremental?



https://gitprotect.io/blog/git-backup-or-git-clone-that-is-the-question/



-->

====Git URLs====

<!--
Git URLs are either HTTPS or SSH



HTTPS
* less setup for basic encrypted transfer in that it doesn't rely on account
* means you don't have to explain ssh-agent

SSH
* key based access lets you identify different sources without username+password



Some have reported the latter is more reliable than the former




https://stackoverflow.com/questions/11041729/why-does-github-recommend-https-over-ssh
-->


====What's with pull requests?====

<!--


In previous systems, we shared a system and we trusted each other.

Today, everyone has their own castle.

We don't share, I don't trust you, and I gatekeep everything you suggest,
''even'' when we use the shared repository model.



Even even if you are trusted and would click OK blindly, that suggestion is an eight-step program.

Because git's way of working has taught us that this is The Way Things Are Done. 

We need, uh, feature branches or something?


So instead of most other systems where you cooperate and can do an add and a commit, 
it's now... checkout, branch, add, commit, push, and then, uh... 

And then you log into the product website called github, because 
* we do not understand git without github,

* pull requests are not really a core git feature
:: (Yes, there's git request-pull but in pragmatic sense it's not quite the same thing)

* we have just collectively forgotten that there are other ways of doing this



-->

====fast forwarding====

<!--
"Fast forwarding" means moving the HEAD pointer to a direct descendant.

You can't fast forward when your copy diverges from upstream - e.g. your loca commits means ''your'' HEAD is not an ancestor of upstream's HEAD, a situation that probably requires a rebase or merge.

"can be fast forwarded" ''roughly'' means that there is no such issue, and that a fetch/update can just pull commits and move your HEAD pointer.
-->

====degit====

Looks to me as if
 degit some-user/some-repo

is functionally much like 
 git clone --depth 1 https://github.com/some-user/some-repo && rm -rf ./some-repo/.git/


It mostly seems used by webdevs who put a template on github, and want to save keystrokes fetching it and leaving no extra mess.
Which is quite useful.


Notes:
* actually does more, e.g. fetches a tgz into a cache in your user dir, which speeds up repeat installs

* https://www.npmjs.com/package/degit?activeTab=readme#wait-isnt-this-just-git-clone---depth-1-

====Unsorted====
See also: (TODO: do so myself)

Reference-like:
* http://gitref.org/
* http://git.or.cz/course/svn.html

Introductions:
* http://marklodato.github.com/visual-git-guide/
* http://scottr.org/presentations/git-in-5-minutes/
* http://www.gitcasts.com/
* https://git.wiki.kernel.org/index.php/GitFaq
* http://progit.org/book/

Discussions and other:
* http://tomayko.com/writings/the-thing-about-git
* http://git-scm.com/

===git GUIs===


In no particular order:
* [https://www.gitkraken.com/ gitkraken] (win+lin+osx)

* [http://git-cola.github.io/ git-cola] (win+lin+osx)

* [http://www.syntevo.com/smartgit/download smartgit] (java)

* gitg (lin)

* comes with git:
** {{inlinecode|git gui}} (more for management, not so polished)
** {{inlinecode|gitk}}  (mostly a viewer)

* [http://www.collab.net/giteyeapp giteye]

* qGit  (mostly a viewer)

* giggle (mostly a viewer)



...also note that various IDEs have integrated git. 
Some of them are quite good, even, and potentially more convenient than anything external.



github-specific
* [https://windows.github.com/ for windows]
* [https://mac.github.com/ for mac]

==Extensions to git==

====Pull requests====
<!--

Say you're a well defined project, or company, where you know everyone and can trust all others.

It can work well enough to give everyone working on it full access to everything, based on specific accounts.
In that if you cannot trust your people to not do stupid things, you ''may'' have problems that software can't solve.


On sites sites that collect unrelated repositories and unrelated people (like the githubs, gitlabs, etc. of this world),
you ''could'' do the same, by defining specific collaborators that share access to a repository.


Yet in more loosely defined projects, you may not want to. 

And if you want relative strangers to be able to contribute code, you barely can (and also don't want to).


So what do you do? Do we fall back to be the 1990s one - "mail me a diff, I'll see"?

Well yes, but updated a bit:

So you want some mechanism to submit something ''that then gets reviewed'' before anything happens.
If acknowledged, it would probably become a merge (because it makes sense to create this change as its own little branch).



This is not quite a core git feature,  
this is a feature most git hosters have added, 

...which is why the last step in tutorials is not a CLI command but "now go to the repo on the github/gitlab website, find the branch, click pull request, select the repo you want them to pull from, and the range of commits you want them to pull"

The response ("Merge pull request") is also web based.


It's a more streamline mouse-click-based variant of (and functionally equivalent to) sending them an email saying 
"please run {{git request-pull}} for this specific range of commits (which started from a common point because I cloned yours earlier)".


This is both useful in that it fills a real need,
and weird in that there apparently is no git way of doing that.





Github calls it a pull request[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests].

Gitlab calls it a merge request[https://docs.gitlab.com/ee/api/merge_requests.html].


...because you are asking someone to pull specific changes from another branch, and merge it into your own code.

Merge request is the clearer name, both intuitively and technically. (Or even branch request) [https://stackoverflow.com/questions/22199432/pull-request-vs-merge-request]




The form it usually takes it to fork the project on that same service,
commit changes to your fork,
and use whatever web interface there is for making a pull request


https://www.atlassian.com/git/tutorials/making-a-pull-request/


https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository


You can then set collaborator permissions

e.g. whether they can delete or force push to a branch -- which is what ''Proteted branches''' are about.


https://docs.github.com/en/rest/collaborators

https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches



-->

====LFS====
{{stub}}


Hosters don't like you pushing large files.


Nor will ''you'', when 
* you realize that changing large files will mean the bulk of space taken by all copies is now versions of that file.
Remember, one of the selling points is that everyone has a full version history {{comment|(yes, you ''can'' actually remove things from that history{{verify}}, but it's not really intended)}}.

* you notice git would taking minutes to do anything, and [[trashing|trashes]] your computer when you try a gc or repack.



So e.g. github warns you above 50MB, and refuses above 100MB, and limits your repository to a few GB.

Other hosters have similar limits.


'''Git LFS (Large File Storage)''' is an extension developed and used by some of these git hosting sites.


It comes down roughly to 
* your repository stores what amounts to a pointer - to a completely separated storage (that we happen to call LFS)
* specific clients know what to do with that


For that to work, in a regular add/commit/clone/pull workflow, '''all collaborating clients (and probably the git hoster) need to support this LFS extension'''.
: A client with LFS support will work transparent in that it will fetch the content that this pointer points to
: A client without LFS support installed will just see files that happen to contain these pointers)


The specific service called LFS has a (rather opaque) set of limits to storage and to bandwidth[https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage].
: so beware - using this for actively changing data is '''effectively a paid service'''


https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-git-large-file-storage

https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage

===github specific===


===="Your main branch isn't protected"====

<!--
This is ''largely'' about projects with configured collaborators. 

It intends to make you think about what others can mess up, and ''maybe'' restrict that using rules.

For projects without collaborators configured, this seems a little like [[fud]].


Such rules are how you can set up
* manual code review
* tests passing

-->

===gitlab specific===

====groups====

https://docs.gitlab.com/ee/user/group/

=====Merge requests=====

Basically the same as [[#Pull_requests|pull requests]]