Difference between revisions of "FPC git"

From Lazarus wiki
Jump to navigationJump to search
Line 154: Line 154:
  
 
=== ls (listing branches) ===
 
=== ls (listing branches) ===
to get a list of branches in Subversion, you use the 'ls' command with a server URL.
+
To get a list of branches in Subversion, you use the 'ls' command with a server URL. By convention, all directories under '/branches' are the names of branches. Branches always exist both on the client(s) and server.
in git this works simpler.
 
  
The list of local branches is obtained using:
+
In git, branches are formalised as part of the version control system: commands deal specifically with branches rather than with paths that are treated as branches. Additionally, git differentiates between remote branches (branches that exist in the repository that you cloned, i.e., in this case on the gitlab server), and local branches (branches that you created on your machine after cloning). The repository that you cloned is referenced using the alias "origin" by default, and the names of remote branches are prepended by this alias.
 +
 
 +
The list of local branches can be obtained using:
 
<pre>
 
<pre>
 
git branch  
 
git branch  
 
</pre>
 
</pre>
 +
By default, the only local branch you will have is <tt>main</tt>, which corresponds to svn trunk. This local branch is automatically created when performing the initial clone operation.
  
The list of remote branches is obtained using:
+
The list of remote branches can be obtained using:
 
 
 
<pre>
 
<pre>
 
git branch -r
 
git branch -r
 
</pre>
 
</pre>
The name of the origin is prepended to the actual branch name. Note that similarly named branches on different origins can have different commits.
+
By default, the remote branches are the branches that exist in the repository on the gitlab server, whose alias is "origin". The local <tt>main</tt> branch automatically ''tracks'' (~ is linked to) the remote <tt>origin/main</tt> branch. Because of this tracking, executing <tt>git pull</tt> resp. <tt>git push</tt> commands while you have your local <tt>main</tt> branch checked out will synchronise the two from resp. to gitlab. See '''switch''' below on how to create more local branches and how to link them to remote branches.
 +
 
 +
{{Note|While git always downloads all branches and their commits by default when cloning or pulling and while you can use their content without a network connection, you cannot directly work on remote branches (since they're remote and not local). Instead, you have to create a local branch that "tracks" this remote branch.}}
 +
{{Note|Do not directly checkout a remote branch. That will put you in a so-called "detached HEAD" state: your working copy will contain the contents from that branch, but you can't commit anything as you can only commit to local branches. You can get out of a "detached HEAD" state by simply checking out another branch.}}
  
 
=== copy (creating a branch) ===
 
=== copy (creating a branch) ===

Revision as of 22:25, 9 June 2021

Git setup

The Git repository is hosted on Gitlab:

https://gitlab.com/freepascal.org/testconversion

The URL to clone the repository is:

https://gitlab.com/freepascal.org/testconversion.git

In order for your commits to be recognized, please configure your local (or better yet, global) git installation to use the address linked to your gitlab acccount.

git config --global user.email your.email.user@youremail.host

This will set your email address for all git repositories you use, and will allow the gitlab interface to correctly link commits to users in its HTML interface.

If you have multiple gitlab (or even github) accounts, you may prefer to set this email only locally:

git config --local user.email your.email.user@youremail.host

this command must be execute in a particular repository, and sets the email address for only that repository.

Branching model

In a first stage, the branching model as used in Subversion will be used: fixes done in trunk, and later merged to the fixes branch.

At a later stage, the branching model may be changed into one of the many git branching schemes.

Windows Git clients

On macOS, Linux & BSD, the git command is installed with the system package manager (you must install XCode command line tools on macOS). On Windows, a separate git client must be installed. There are many available, but the following are popular ones:

  • Git for windows: a command-line client with a bash shell, so you can copy & paste commands you find on internet:
https://gitforwindows.org/
  • TortoiseGit integrates with the Windows explorer, much like TortoiseSVN does:
https://tortoisegit.org/
if you already have TortoisSVN installed, both can work side-by-side.
  • Sourcetree is a free client for Windows and macOS:
https://www.sourcetreeapp.com/
It is made by the people from bitbucket.
  • Smartgit runs on Windows, Linux and macOS:
https://www.syntevo.com/smartgit/
  • The VSCode and Atom editors have git support built in.

Common SVN operations in Git

Check out

To check out a new copy of a repository is called 'cloning' in git.

git clone https://gitlab.com/freepascal.org/testconversion

As in subversion, you can give it another name:

git clone https://gitlab.com/freepascal.org/testconversion myconversion

This operation can take a while, the FPC source base is large.

Update

To update your source code with the changes in the remote repository, is called 'pulling' in git:

git pull

Note that in difference with subversion, git always updates the whole repository.

revert

If you have made some changes locally and wish to undo them, you can do a 'reset' in git:

git reset --hard

This will undo any changes you made. You can undo changes to individual files by specifying them at the end of the command.

Warning-icon.png

Warning: The above assumes you didn't do any git add (see next section): changes staged to be committed will not be reverted. You first have to unstage them with with the git reset command (i.e., without the --hard option).

add (adding new files)

Subversion uses the add command to add a file to the versioning system. This is no different in git: If you want to add a file, you must add it first, like this:

git add newfile.pas

You must then (just as in subversion) still commit this newly added file.

rm (removing files)

Subversion uses the rm command to add a file to the versioning system. This is no different in git:

git rm nolongerneededfile.pas

You must then (just as in subversion) still commit this removed file.


mv (renaming files)

Subversion uses the rm command to rename a file in the versioning system. This is no different in git:

git mv oldfile.pas newfile.pas

You must then (just as in subversion) still commit this change.

As in subversion, you can move one or more files to another directory:

git mv file1.pas file2.pas somesubdir


commit

If you have made some changes locally and wish to commit them, this is a 2-step process:

git add myfile.pas

This schedules the file to be committed (called staging in git). You can add as many files as you want like this.

Light bulb  Note: An easy way to remember this is that svn requires the same for newly added files. Git extends this to all changes, because that way you not only can selectively schedule individual new files for the next commit, but also changes to existing files. The opposite of git add is git reset (without the --hard parameter!)
Light bulb  Note: To see the changes that have been staged/scheduled for commit, use git diff --cached. Plain git diff will show local changes that are not (yet) staged.

When you are ready to commit what you have staged, you can commit:

git commit -m '* Some nice comment telling what you did'

In fact, if you're in a hurry and know you want to commit a file, you can combine the 2 commands;

git commit -m '* Some nice comment telling what you did' myfile.pas

If you are really in a hurry, you can commit all changed files in one fell swoop:

git commit -m '* Some nice comment telling what you did' -a

But it is not really recommended to use this, as it will commit all changes in your local copy, not just the ones in the current working directory.

At this point, your changes have been saved locally, but have not yet been sent to the remote repository. To do that, you must additionally send the changes to the remote repository. This is called pushing:

git push

That will send all locally committed changes to the server. Obviously only changes that have not yet been sent previously are sent.

diff (show changes to working copy)

In svn, you can see the changes that have been made but have not yet been committed with diff. This is also correct in git:

git diff

will show all not yet staged or committed changes made to your working copy.

You can view this for a single file as well:

git diff myfile.pas

will show unstaged changes made to your working copy of myfile.pas.

If you have already staged one or more files (i.e. marked for inclusion in the next commit), the above will not show them in the generated diff.

If you wish to see the changes in these files as well, you must add the --cached command-line option:

git diff --cached


ls (listing branches)

To get a list of branches in Subversion, you use the 'ls' command with a server URL. By convention, all directories under '/branches' are the names of branches. Branches always exist both on the client(s) and server.

In git, branches are formalised as part of the version control system: commands deal specifically with branches rather than with paths that are treated as branches. Additionally, git differentiates between remote branches (branches that exist in the repository that you cloned, i.e., in this case on the gitlab server), and local branches (branches that you created on your machine after cloning). The repository that you cloned is referenced using the alias "origin" by default, and the names of remote branches are prepended by this alias.

The list of local branches can be obtained using:

git branch 

By default, the only local branch you will have is main, which corresponds to svn trunk. This local branch is automatically created when performing the initial clone operation.

The list of remote branches can be obtained using:

git branch -r

By default, the remote branches are the branches that exist in the repository on the gitlab server, whose alias is "origin". The local main branch automatically tracks (~ is linked to) the remote origin/main branch. Because of this tracking, executing git pull resp. git push commands while you have your local main branch checked out will synchronise the two from resp. to gitlab. See switch below on how to create more local branches and how to link them to remote branches.

Light bulb  Note: While git always downloads all branches and their commits by default when cloning or pulling and while you can use their content without a network connection, you cannot directly work on remote branches (since they're remote and not local). Instead, you have to create a local branch that "tracks" this remote branch.
Light bulb  Note: Do not directly checkout a remote branch. That will put you in a so-called "detached HEAD" state: your working copy will contain the contents from that branch, but you can't commit anything as you can only commit to local branches. You can get out of a "detached HEAD" state by simply checking out another branch.

copy (creating a branch)

To create a branch from the current working directory situation, you can create a branch like this:

git branch mybugfix

this will create a branch mybugfix from the current branch at the current commit. But it does not yet make this the active branch.

You need to check out the newly made branch first:

git checkout mybugfix

Again, the two operations can be performed in 1 command:

git checkout -b mybugfix

switch (checking out a branch)

To switch to an existing local branch `mybugfix`, you can use the checkout command:

git checkout mybugfix

this will check out branch mybugfix. If there are any uncommitted changes which would cause a conflict, git will refuse the checkout.

To switch to a remote branch `mybugfix2`, which does not exist yet locally, you can also use the checkout command:

git checkout mybugfix2

this will check out branch mybugfix2 and automatically set it up to track the remote branch. Here again, if there are any uncommitted changes which would cause a conflict, git will refuse the checkout.

Note that if the branch does not exist remotely, this will simply create a new branch locally. It is better to be explicit:

git checkout -b mybugfix2 --track origin/mybugfix2

If you created a branch locally which does not yet exist on the server, made some modifications, and you wish to push this branch to the server, you must tell this to git when pushing:

git push -u origin/mybugfix mybugfix

the -u origin/mybugfix tells git all it needs to know to connect the local with the remote branch.

merge (merging the changes in 2 branches)

To merge changes in 2 branches, you use the merge command. If we want to merge the changes in mybugfix to fixes then we do:

git checkout fixes
git merge mybugfix

blame (check who made modifications)

To see who changes what line (and in what commit) svn offers you the 'blame' command. The same command exists in git.

git blame yourfile.pas

status (check status of files)

To see whether there are any changed files in your working repository, svn offers the 'status' command. The same command exists in git.

git status 

will present you with all changed, staged and new files in the repository.

If you want only the status of files below a certain directory, you can specify the name of the directory. So to get the changes in the current working directory (or below) that would be:

git status .

will present you with all changed, staged and new files in the current directory. This is the default behaviour of svn.

shelve (temporarily undo changes)

Subversion has an (experimental) feature that allows to temporarily set aside changes to your working copy : shelve. This feature exists since a long time in git and is called stash:

git stash 

will set aside any changes to the working copy, and restore the working copy to the state it would be in if you did a 'git pull' (or svn update).

To re-apply the changed you set aside, you can execute the following command:

git stash pop

info (get working dir and server info)

In subversion, you can get information about the current working directory and remote server configuration using svn info. Since git is a distributed system, no direct equivalent of the info command exists: there is no single server, and the revision number as known in subversion does not exist.

The following script attempts to display similar information as the svn info command:

#!/bin/bash

# author: Duane Johnson
# email: duane.johnson@gmail.com
# date: 2008 Jun 12
# license: MIT
# 
# Based on discussion at http://kerneltrap.org/mailarchive/git/2007/11/12/406496

pushd . >/dev/null

# Find base of git directory
while [ ! -d .git ] && [ ! `pwd` = "/" ]; do cd ..; done

# Show various information about this git directory
if [ -d .git ]; then
  echo "== Remote URL: `git remote -v`"

  echo "== Remote Branches: "
  git branch -r
  echo

  echo "== Local Branches:"
  git branch
  echo

  echo "== Configuration (.git/config)"
  cat .git/config
  echo

  echo "== Most Recent Commit"
  git --no-pager log  -n1
  echo

  echo "Type 'git log' for more commits, or 'git show' for full commit details."
else
  echo "Not a git repository."
fi

popd >/dev/null

Note that this script will also work in the Windows environment if you have the windows git client installed, because it comes with a minimal unix environment.

file properties (EOL handling etc.)

Subversion allows you to set some properties on files. There are 'reserved' properties that svn itself uses, for example to handle EOL handling and file type. Because git operates on diffs and not on files, no similar concept exists.

However, git does allow you to set global or local attributes for classes of files. These are in the .gitattributes file. That file should be located in the root of your repository, and can contain some attributes. For example:

*               text=auto
*.txt		text
*.vcproj	text eol=crlf
*.sh		text eol=lf
*.jpg		-text

This is a regular file which you can (and must) add with git add so it is saved for all users.