Re: Dokumenting api-paths.txt

From: Stefan Beller <stefanbeller@googlemail.com>
Date: Aug 21, 2013, 22:43 UTC
Message-ID: <52154282.60701@googlemail.com>
In-Reply-To: <20130820215911.GJ4110@google.com>

On 08/20/2013 11:59 PM, Jonathan Nieder wrote:

Show 33 quoted lines

> Stefan Beller wrote:
>>>> On 08/20/2013 03:31 PM, Johannes Sixt wrote:
>>>>> Stefan Beller wrote:
> 
>>>>>> +    packdir = mkpathdup("%s/pack", get_object_directory());
>>>>>> +    packtmp = mkpathdup("%s/.tmp-%d-pack", packdir, getpid());
>>>>>
>>>>> Should this not be
>>>>>
>>>>>     packdir = xstrdup(git_path("pack"));
>>>>>     packtmp = xstrdup(git_path("pack/.tmp-%d-pack", getpid()));
> [...]
>> So if I have 
>> 	packdir = xstrdup(git_path("pack"));
>> 	...
>> 	path = git_path("%s/%s", packdir, filename)
>>
>> This produces something as:
>> .git/.git/objects/pack/.tmp-13199-pack-c59c5758ef159b272f6ab10cb9fadee443966e71.idx
>> definitely having one .git too much.
> 
> The version with get_object_directory() was right.  The object
> directory is not even necessarily under .git/, since it can be
> overridden using the GIT_OBJECT_DIRECTORY envvar.
> 
>> Also interesting to add would be that git_path operates in the
>> .git/objects directory?
> 
> git_path is for resolving paths within GIT_DIR, such as
> git_path("config") and git_path("COMMIT_EDITMSG").
> 
> Jonathan
>

Before we're doing double work, I just wrote down my understanding so far. Feel free to tweak it, or remove obvious parts.

Thanks, Stefan

--- path API ========

The functions described in this document are meant to be used when dealing with pathes in the filesystem. The functions are just for the string manipulations of the pathes, none of the functions touches the actual filesystem.

`mkpath`::
	The parameters are in printf format. This function can be
	used to construct short-lived filename strings. It is meant
	to be used for direct use in system functions such as
	dir(mkpath("%s/pack", get_objects_directory())).
	The return value is a pointer to such a sanitized filename
	string, but it resides in a static buffer, so it will
	be overwritten by the next call to mkpath (or other functions?)
	This function only does string handling. It doesn't actually
	change anything on the filesystem. (This is not Gits mkdir -p)

`mkpathdup`::
	The same as mkpath, but the memory is duplicated into a new
	buffer, so it is not short-lived, but stays as long as the
	caller doesn't free the memory, which the caller is supposed
	to do.

`xstrdup`::
	Duplicates the given string, making the caller responsible
	to free the return value. Basically the same as strdup(2)
	with errorhandling.

	I am not sure if this belongs into the path api documentation,
	but it's not documented anywhere else.

`git_path`::
	git_path is for resolving paths within GIT_DIR, such as
	git_path("config") and git_path("COMMIT_EDITMSG").
	This is similar to mkpath, returning a pointer to a static
	buffer, which may be overwritten soon.

`git_pathdup`::
	The same as git_path, but creating a new buffer. The caller
	is responsible to free the returned buffer.

`git_path_submodule`::

`mksnpath`::

`git_snpath`::

`sha1_file_name`::
	Returns the filename to a given sha1 value within
	the objects directory.

`sha1_pack_name`::
	
`sha1_pack_index_name`::